@aliyunrds/ctxdb

Unified access layer for RDS ContextDatabase. One ctxdb CLI (memory + KB ops), one setup installer (--agent <…> for hooks/skills, bare for CLI-only), per-agent SKILL.md — supports multiple code agents from a single package.

| Agent | Hooks | Skill install path | Skill style | |---|---|---|---| | qoder | ✅ UserPromptSubmit + Stop + SessionStart | ~/.qoder/skills/ctxdb/ | hooks-driven (auto capture/recall) | | qoderwork | ✅ UserPromptSubmit + Stop + SessionStart | ~/.qoderwork/skills/ctxdb/ | hooks-driven (auto capture/recall) | | codex | ✅ UserPromptSubmit + Stop + SessionStart | ~/.codex/skills/ctxdb/ | hooks-driven (auto capture/recall) | | claude | ✅ UserPromptSubmit + Stop + SessionStart | ~/.claude/skills/ctxdb/ | hooks-driven (auto capture/recall) | | opencode | Plugin shim (~/.config/opencode/plugins/ctxdb.ts) | ~/.config/opencode/skills/ | in-process plugin (auto capture/recall + KB catalog injection) |

Config and logs live under ~/.ctxdb/. ~/.ctxdb/ctxdb.json is one file, but runtime config is isolated per agent under agents.qoder, agents.qoderwork, agents.codex, agents.claude, and agents.opencode. (Pre-2026-05-23 installs used ~/.ctxdb.json at the home root; running ctxdb setup --agent <name> migrates the file into the selected agent section.)

Install

npm install -g @aliyunrds/ctxdb

# Qoder (hooks + skill)
ctxdb setup --agent qoder --api-key ctxdb-...
# QoderWork (hooks + skill)
ctxdb setup --agent qoderwork --api-key ctxdb-...
# Codex (hooks + skill)
ctxdb setup --agent codex --api-key ctxdb-...
# Claude Code (hooks + skill)
ctxdb setup --agent claude --api-key ctxdb-...
# OpenCode (plugin shim + skill)
ctxdb setup --agent opencode --api-key ctxdb-...

# --base-url defaults to https://context-database.aliyuncs.com (public prod).
#   Pass --base-url <host> only if you target a different deployment
#   (e.g., a pre / staging host, or a self-hosted instance).
# --user-id  defaults to "default". Pass --user-id <bucket> only if you
#   need to isolate this install from another access layer or machine
#   sharing the same workspace (see "Configuration" below).

# Verify
ctxdb status --json

Setup first checks that the target agent home exists (~/.qoder, ~/.qoderwork, ~/.codex, or ~/.claude). If the directory is missing, install or start that agent once before running ctxdb setup --agent <name>. OpenCode is XDG-style: setup creates ~/.config/opencode and ~/.config/opencode/plugins when they are missing.

For qoder, qoderwork, codex, and claude, restart the harness (CLI: just exit + restart; app: Cmd+R or quit/relaunch) so it picks up the new hooks/skill. For codex, setup also writes [features].hooks = true into ~/.codex/config.toml (creating the file if missing) — Codex won't fire any hook entries without it. On first use Codex may prompt you to trust the new hook commands. For opencode, restart OpenCode so it loads ~/.config/opencode/plugins/ctxdb.ts.

What it does

For qoder, qoderwork, codex, and claude, hooks fire automatically:

| Trigger | Hook | What runs | |---|---|---| | Session starts | SessionStart | Build a short cwd/git-signal query, recall relevant memories, and inject warm-up context as additionalContext | | User submits a prompt | UserPromptSubmit | Search /v3/memories/search/, format a <recalled-memories> block, inject as additional context. By default only memory is recalled. Set recall_knowledge: true in the selected agent config to also pull KB chunks into a <external-knowledge> block; otherwise the recommended path for KB is the agent calling ctxdb kb search --agent <name> explicitly when the user asks (see SKILL.md) | | Agent finishes its turn | Stop | Read transcript, detect KB-upload turns and skip capture (so uploaded content doesn't bleed into long-term memory), slice the current turn, sanitize the input, POST to memory store |

Implementation note: qoder/Claude consume the JSON hookSpecificOutput.additionalContext shape; Codex has been verified on this machine through ~/.codex/hooks.json, [features].hooks = true, and hook audit logs, where non-empty stdout from UserPromptSubmit/SessionStart is treated as injected context. The same hook core is shared; setup passes --agent=<name> so each hook reads its own config section.

For opencode, ctxdb setup --agent opencode writes a small re-export shim at ~/.config/opencode/plugins/ctxdb.ts. The shim points into this package's bundled dist/opencode/src/index.ts, so npm update -g @aliyunrds/ctxdb updates the plugin implementation without copying source into the user config directory. ctxdb upgrade --agent opencode refreshes the absolute shim target after package moves.

CLI

ctxdb ships 18 subcommands:

• Top-level: setup / status / ping / uninstall / upgrade
• Memory: memory add|search|list|get|update|delete
• KB: kb upload-text|upload-file|list|documents-list|document-get|search

See ctxdb --help.

setup without --agent writes agents.default in ~/.ctxdb/ctxdb.json (CLI-only, no hooks or skills); with --agent <qoder|qoderwork|codex|claude|opencode> it writes agent config and installs hooks/plugins + skills for that harness. Memory and KB commands also accept --agent <name> so agents use their own config section; when omitted, CTXDB_AGENT env wins, otherwise agents.default is used. uninstall without --agent loops every supported agent; with --agent <name> it targets just that one. teardown is an alias for uninstall.

memory add … --no-infer stores the text verbatim (skips server-side LLM fact-extraction). Use it when the user explicitly asks for a verbatim memory ("记住 / 请记忆 / 原文记下"); without --no-infer the server may rewrite, merge, or skip details.

kb search <query> [--kb=name1,name2] [--top-k=N] [--threshold=F] is the agent-driven KB recall path — calls POST /v1/knowledge/query directly (distinct from memory search --knowledge, which is a memory + KB hybrid search). The SKILL points the agent here when the user explicitly asks for KB lookup ("结合知识库查询" / "从知识库召回"). --kb is comma-separated; omit it to search across all KBs.

Configuration

Lives at ~/.ctxdb/ctxdb.json (co-located with logs at ~/.ctxdb/logs/). Schema:

{
  "version": 2,
  "agents": {
    "qoder": {
      "api_key": "ctxdb-...",
      "base_url": "https://context-database.aliyuncs.com",
      "user_id": "default",
      "auto_capture": true,
      "auto_recall": true,
      "warmup_recall": true,
      "recall_knowledge": false,
      "top_k": 5,
      "threshold": 0.4,
      "knowledge_top_k": 6,
      "debug": false
    },
    "qoderwork": { "...": "same schema, independent values" },
    "codex": { "...": "same schema, independent values" },
    "claude": { "...": "same schema, independent values" },
    "opencode": { "...": "same schema, independent values" }
  }
}

Agent selection is driven by --agent <qoder|qoderwork|codex|claude|opencode|default> on every CLI invocation, falling back to CTXDB_AGENT env, then to default. There is no default_agent field — older installs that have one written get it dropped on the next save.

Field reference:

| Key | Type | Default | Meaning | |---|---|---|---| | user_id | str | "default" | mem0-layer bucket key on every capture/recall call. The server's tenant isolation runs on member_id (injected from X-API-Key), so this is an optional per-user/agent slice. Override with ctxdb setup --agent <a> --user-id <bucket> or CTXDB_USER_ID=<bucket> when you need to isolate this install from another access layer or machine sharing the same workspace | | auto_capture | bool | true | Stop hook captures each turn into long-term memory for the selected agent | | auto_recall | bool | true | UserPromptSubmit hook recalls memory on each user prompt for the selected agent | | warmup_recall | bool | true | SessionStart hook recalls cwd/git-related memories for the selected agent | | recall_knowledge | bool | false | When auto_recall is on, also pull KB chunks alongside memory. Default is off — the recommended KB-recall path is the agent calling kb search --agent <name> explicitly when the user asks | | top_k / threshold | int / float | 5 / 0.4 | Memory recall pagination + similarity floor. 5 keeps the codex TUI hook context: ... line short enough to scan and bounds token spend on the modal recall path; raise it per-agent if you want more candidates | | knowledge_top_k | int | 6 | KB chunks pulled per recall (only effective when recall_knowledge: true) | | debug | bool | false | Verbose hook logging (~/.ctxdb/logs/ctxdb.log) |

Env-var overrides apply to the selected agent config (env wins): CTXDB_AGENT / CTXDB_API_KEY / CTXDB_BASE_URL / CTXDB_USER_ID.

Architecture

@aliyunrds/ctxdb            ← this package (CLI + setup + hooks + skills)
       │
       ├─ bundles OpenCode plugin source in dist/opencode/src
       │
       └─ depends on @aliyunrds/ctxdb-shared  ← input sanitation,
                                          prompt-injection defenses,
                                          memory/KB types, recall pipeline
                                          (also consumed by openclaw_memory_rds_ctxdb)

Two npm packages total. @aliyunrds/ctxdb-shared stays separate because OpenClaw's plugin fork also depends on it; this package owns everything user-facing (CLI bin, installer, per-agent skills, hooks).

Uninstall

⚠️ Order matters. npm 7+ removed the preuninstall / postuninstall lifecycle hooks — npm uninstall -g does not run any cleanup we ship. If you npm uninstall first you'll leave agent hook entries pointing at a now-missing binary, plus orphaned skills and ~/.ctxdb/ state. Always run ctxdb uninstall first, then npm uninstall -g.

Full removal (recommended)

# 1. Strip hooks + skills + (optionally) config + logs while the binary still works.
ctxdb uninstall --purge-all     # everything: hooks, skills, ~/.ctxdb/ctxdb.json, ~/.ctxdb/logs/

# 2. Then drop the npm binaries.
npm uninstall -g @aliyunrds/ctxdb @aliyunrds/ctxdb-shared

After step 1, ctxdb uninstall prints the exact npm uninstall command to run next — copy it from your terminal.

Partial removal

# Per-agent only — unwires hooks, removes ~/.<agent>/skills/ctxdb, AND
# deletes agents.<X> from ~/.ctxdb/ctxdb.json. Other agents' sections are
# preserved verbatim. If <X> was the last configured agent, ~/.ctxdb/ctxdb.json
# itself is unlinked so a future `ctxdb setup --agent <X>` runs through the
# first-time install path cleanly.
ctxdb uninstall --agent qoder
ctxdb uninstall --agent qoderwork
ctxdb uninstall --agent codex
ctxdb uninstall --agent claude
ctxdb uninstall --agent opencode

# Wholesale across all agents, but keep config + logs for re-setup later:
ctxdb uninstall                  # all agents, keeps ~/.ctxdb/{ctxdb.json,logs/}
ctxdb uninstall --purge-config   # also deletes ~/.ctxdb/ctxdb.json
ctxdb uninstall --purge-logs     # also deletes ~/.ctxdb/logs/

What uninstall does (and doesn't) touch

• Hook entries in ~/.qoder/settings.json, ~/.codex/hooks.json, and ~/.claude/settings.json: stripped precisely by marker (_ctxdb = @aliyunrds/ctxdb, plus legacy keys _ctxdbQoder / _ctxdbPackage and the legacy @aliyunrds/ctxdb-qoder value for installs predating the unified marker). Any hooks you added yourself stay. A timestamped *.bak-ctxdb-<TS> is written before each modification (rotation keeps the 5 most recent).
• Skill directories: ~/.<agent>/skills/ctxdb/ for each set-up agent, plus legacy dirs (ctxdb-qoder, rds-ctxdb-qoder, qoder-ctxdb) under ~/.qoder/skills/ from older package names.
• ~/.ctxdb/ state: only with --purge-config / --purge-logs / --purge-all. Defensive: --purge-all removes the ~/.ctxdb/ root only if it's empty after the named files are deleted (won't blanket-rm an unknown directory).
• ~/.codex/config.toml [features].hooks: NOT reverted. Setup adds hooks = true so Codex will fire ctxdb's hook entries; uninstall leaves the flag alone because (a) the user may have wanted it on for non-ctxdb hooks, and (b) it's harmless when ~/.codex/hooks.json is empty. If you want it off, edit the file by hand.
• npm itself: never. ctxdb uninstall does not call your host package manager — that's the second command above.

Remote SSH (Qoder IDE)

When you connect to a remote host via Qoder IDE's SSH session, ctxdb does not travel with the Qoder server. Qoder syncs its own server bits to the remote machine, but ~/.qoder/{settings.json, skills/} and ~/.ctxdb/ctxdb.json are per-host — your local hooks, config, and skill are not propagated.

To enable autoCapture / autoRecall in the remote session, run the same install on the remote machine:

# on the remote host
npm install -g @aliyunrds/ctxdb
ctxdb setup --agent qoder --api-key ctxdb-...
# Both --base-url and --user-id are optional; they default to the public
# prod host and the "default" bucket respectively. Override either when
# you target a non-prod deployment or want per-host bucket isolation.

Each remote host needs its own one-time setup. Omitting --user-id lands every host on the shared "default" bucket, so memory flows freely across machines that share an API key. Pass a distinct --user-id per host when you want per-host bucketing.

Lightweight (no-node) alternative

SKILL-one-in-all.md is a single-file bash-only skill: zero install, no node runtime, but no hooks and no streaming/upload helpers. Use it when you can't or don't want to ship the npm package; use this package when you want hooks (qoder/codex/claude) or a richer CLI surface.

Developer docs

Maintainer-facing docs (source layout, dev/test workflows, server-config archives) live in the project's internal notebooks and are not packaged with this release. npm consumers can ignore this section.

License

Apache-2.0