@aliyunrds/ctxdb

Unified access layer for RDS ContextDatabase. One ctxdb CLI (memory + KB ops), one setup installer (--agent <…> for one hooks/skills integration, --all for every detected integration, 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) | | qwenwork | ✅ UserPromptSubmit + Stop + SessionStart | ~/.qwenwork/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) | | hermes | ✅ pre_llm_call + post_llm_call | ~/.hermes/skills/ | shell hooks (auto capture/recall + first-turn warmup) |

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.qwenwork, agents.codex, agents.claude, agents.opencode, and agents.hermes. (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

Recommended: console-generated installer command

The customer console supplies the selected Agent and API key to one of two standalone public files. Replace <public-oss-url> with the release-owned OSS base URL:

# macOS / Linux
curl -fsSL <public-oss-url>/install.sh | \
  bash -s -- --agent codex --api-key 'ctxdb-...'

# Windows PowerShell
& ([ScriptBlock]::Create((irm '<public-oss-url>/install.ps1'))) `
  -Agent codex -ApiKey 'ctxdb-...'

Windows Command Prompt uses the same install.ps1; there is no third CMD artifact:

powershell.exe -NoProfile -Command "& ([ScriptBlock]::Create((irm '<public-oss-url>/install.ps1'))) -Agent 'codex' -ApiKey 'ctxdb-...'"

--agent openclaw / -Agent openclaw takes a dedicated plugin flow instead of ctxdb setup: the installer requires an existing openclaw CLI, runs openclaw plugins install openclaw_memory_rds_ctxdb, openclaw plugins enable openclaw_memory_rds_ctxdb, and openclaw ctxdb init --api-key <key>, then prints openclaw gateway restart for the user to run. It never installs Node.js, npm packages, or the ctxdb CLI on this path.

An agent-readable manual, bootstrap/install.md, is published alongside the scripts. A customer's coding agent can be pointed at its public URL to run the same four-stage flow by hand under the same safety boundaries (used when the scripts are unavailable or blocked by local policy).

The installer shows four stages: check runtime, install the CLI, configure the Agent, and verify the connection. It requires Node.js 20 or newer and the npm executable shipped beside that exact Node.js runtime. If Node.js is absent, it can offer one reviewed Node.js 22 action after explicit confirmation. If an existing Node.js is old, broken, or missing its sibling npm, it stops with upgrade/repair guidance and does not install another private runtime.

The API key is passed directly to ctxdb setup and stored in ~/.ctxdb/ctxdb.json; installer-controlled output redacts the complete value. The generated command itself contains the key, so treat it as a credential and follow the local shell-history policy. The installer never retries with sudo, silently elevates, or edits a shell/PowerShell profile. If the npm global prefix is not writable, it uses a user-only prefix and prints one PATH follow-up.

Immediately before setup, the installer saves an opaque, private temporary copy of ~/.ctxdb/ctxdb.json. If setup fails, it prints the original setup diagnostic, restores the previous config exactly, or removes the incomplete new config when none existed before. Hooks, plugins, and skills may already have changed; fix the reported cause and rerun the same command to repair them. A later status failure does not roll back a setup that already succeeded.

Add --dry-run on macOS/Linux or -DryRun on Windows to preview the same four stages without prompting, installing Node.js or ctxdb, writing a prefix probe, or running setup/status:

curl -fsSL <public-oss-url>/install.sh | \
  bash -s -- --agent codex --api-key 'ctxdb-...' --dry-run

& ([ScriptBlock]::Create((irm '<public-oss-url>/install.ps1'))) `
  -Agent codex -ApiKey 'ctxdb-...' -DryRun

Dry run still validates the required parameters and inspects the local runtime, but it does not contact the npm registry or validate the API key, connectivity, or Agent integration. Its output always redacts the supplied key.

For review-first installation, download the matching file, verify its published SHA-256, inspect it, and run the local copy with the same parameters.

Manual setup and local configuration management

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-...
# QwenWork (hooks + skill)
ctxdb setup --agent qwenwork --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-...
# Hermes (pre_llm_call recall/warmup + post_llm_call capture + skill; macOS/Linux)
ctxdb setup --agent hermes --api-key ctxdb-...

# Detect and configure every supported Agent already used on this host.
ctxdb setup --all --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 --agent codex --json
ctxdb status --all --json

setup --all and status --all use one read-only detector and return Agents in SUPPORTED_AGENTS order. Qoder/QoderWork/Codex/Claude require an existing primary or supported variant home. OpenCode and Hermes are selected when their home exists or their canonical executable is discoverable on PATH. Detection does not create files, does not use an existing ctxdb profile as evidence, and never selects default or OpenClaw. If nothing is detected, the command exits non-zero and asks the user to install/start an Agent once or use explicit --agent <name>.

When ctxdb setup --all is invoked without --api-key, the CLI snapshots each selected Agent's effective configuration before any setup write. Credential priority is --api-key, CTXDB_API_KEY, the Agent profile, then the default profile. This means a key already configured on agents.default is reused for detected Agents that do not have their own key. An Agent with no effective key is reported failed without stopping later Agents. Supplying one explicit key applies it to every selected Agent. Batch output includes per-Agent results and one deduplicated uninstall-order hint, including after a partial failure.

The same two commands cover later management without a separate wizard:

# Add another Agent
ctxdb setup --agent claude --api-key 'ctxdb-...'

# Repair hooks/plugin/skills using the Agent's stored configuration
ctxdb setup --agent codex

# Replace only this Agent's API key
ctxdb setup --agent codex --api-key 'ctxdb-new-...'

# Inspect current local/configuration/connectivity state
ctxdb status --agent codex --json

Setup first checks that the target agent home exists (~/.qoder, ~/.qoderwork, ~/.qwenwork, ~/.codex, or ~/.claude; the declared CN variant home also satisfies this check). Setup writes hooks and skills only into homes that already exist, so a CN-only install does not create the international product home, and vice versa. If no home exists, install or start that agent once before running ctxdb setup --agent <name>. OpenCode and Hermes are config-dir style: setup creates ~/.config/opencode / ~/.hermes when they are missing.

For qoder, qoderwork, qwenwork, 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. For hermes, setup also checks ~/.hermes/shell-hooks-allowlist.json; it reports setup as incomplete until both ctxdb hook commands are approved.

Hermes owns this security allowlist, so ctxdb only checks it and never writes approvals. Approve the ctxdb pre_llm_call and post_llm_call hooks with:

hermes --accept-hooks chat

This command opens an interactive chat. After Hermes starts, exit the chat and rerun ctxdb setup --agent hermes; the allowlist check should then pass. Finally, restart any running Hermes CLI or gateway process so it reloads config.yaml and registers the hooks. The public bootstrap installer preserves the hooks in this allowlist-pending state and reports these commands as required follow-up instead of rolling the integration back.

The two ctxdb events are pre_llm_call and post_llm_call. ctxdb status --agent hermes also verifies their exact (event, command) pairs and reports the specific missing approval.

Update

ctxdb update (alias: ctxdb upgrade) now updates the package from npm by default, then re-runs the setup lifecycle for every configured built-in agent using the credentials already stored in ~/.ctxdb/ctxdb.json:

ctxdb update

# Limit setup to one configured agent.
ctxdb update --agent codex

# Skip the npm step and only re-run setup (also used internally after install).
ctxdb update --no-self-update

For npm-installed copies, eligible direct ctxdb commands use a detached version check regardless of whether stderr is a TTY or an Agent-routing flag is present. Checks run on a best-effort daily interval after either a recorded success or failure, so Agent shell tools can receive update information without following a specific invocation shape. The command never waits for npm: a newly discovered release can be shown only on a later invocation. A successful command may append this informational hint to stderr:

ctxdb: update available v1.0.2 → v1.1.0; update with `ctxdb update` (informational only; do not run automatically).

Hints use a best-effort global three-day quiet period, so a higher target version does not bypass a recent reminder. Explicit --json, CI, ctxdb update / ctxdb upgrade, and non-npm layouts remain silent. Non-JSON automation may receive the advisory stderr line; use --json when a single machine-readable document is required, or set CTXDB_DISABLE_UPDATE_CHECK=1 to opt out completely. Concurrent commands may rarely duplicate an advisory hint; the notifier does not add locking to the requested command path.

The notifier only reads/writes ~/.ctxdb/cache/version-check.json; it never installs a package or changes agent setup. Updating remains an explicit ctxdb update action for the Agent or user to choose after seeing the hint.

The existing --self-update flag remains accepted for compatibility, but is no longer required. If the npm version check, global install, or setup pass fails, ctxdb prints the manual recovery commands:

npm install -g @aliyunrds/ctxdb
ctxdb setup

What it does

For qoder, qoderwork, qwenwork, 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 context into an <external-knowledge> block; graph synthesis and document evidence are labeled separately inside that wrapper. 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 create/update turns and skip capture (so document 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 copies the self-contained plugin bundle to ~/.config/opencode/plugins/ctxdb-bundle.js and writes a re-export shim at ~/.config/opencode/plugins/ctxdb.ts referencing it via the relative path ./ctxdb-bundle.js (Bun on Windows can't resolve absolute-path specifiers from a .ts shim). ctxdb upgrade --agent opencode re-copies the bundle + refreshes the shim.

For hermes, ctxdb setup --agent hermes writes two shell hooks under ~/.hermes/config.yaml:

• pre_llm_call maps to recall on each user prompt and first-turn warmup. Hermes does not persist hook context into conversation history, so ctxdb re-injects the KB catalog on every user turn even when kb_catalog_injection keeps its default "session_start" value; this prevents the catalog from disappearing after turn one.
• stdout uses Hermes' {"context":"..."} protocol.
• post_llm_call captures extra.user_message + extra.assistant_response without a transcript file, while extra.conversation_history supplies current-turn tool calls for the B-3c KB create/update guard.

CLI

ctxdb ships grouped non-interactive commands:

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

See ctxdb --help.

Debug control and recall replay

Debug is configured per existing Agent profile without editing JSON manually:

ctxdb debug enable --agent=codex
ctxdb debug disable --agent=codex
ctxdb debug recall --session=<host-session-id>
ctxdb debug recall --event=<recall-event-id> --full
ctxdb debug recall --event=<recall-event-id> --json

Agent resolution follows the rest of the CLI: explicit --agent, then CTXDB_AGENT, then agents.default. Enable/disable is local-only: it updates only agents.<name>.debug, makes no network request, and does not reinstall hooks, plugins, or skills. It requires that profile to already exist.

The only official-production URL currently allowlisted is exactly https://context-database.aliyuncs.com (a trailing slash is equivalent). Policy is evaluated after profile/default inheritance and CTXDB_BASE_URL. Any other complete URL—including pre-production domains, numeric IPs, localhost, HTTP, alternate ports or paths—and any invalid URL forces effective debug on. ctxdb debug disable then fails without modifying the profile. The stored preference is kept separately, so returning to the allowlisted URL restores it. ctxdb status reports debug (effective), debug_configured, debug_forced, and debug_reason (non_production_base_url when forced).

Effective debug writes full-fidelity recall records for qoder, qoderwork, qwenwork, codex, claude, opencode, and hermes to ~/.ctxdb/logs/recall-trace.jsonl. The trace contains the complete query, complete returned memory/KB candidates, local selected/excluded outcome, and the exact context injected into the model. This can contain sensitive project or customer text. The file is local-only, created with mode 0600, rotated at 10 MiB, and retains at most five rotated generations. API keys, Authorization headers, full config objects, and unrelated HTTP bodies are not recorded. Trace I/O is fail-open and cannot block a hook.

Each attempt has a recall_event_id; all attempts in one host conversation carry its local session_id. This is distinct from the service run_id: capture continues sending the host session as run_id, while automatic recall never sends run_id because doing so would narrow long-term retrieval to one session. A recall.start without a matching recall.finish means the hook was interrupted or terminated before it could record a completed outcome; it must not be interpreted as a completed timeout. Disabling debug stops future writes but leaves existing trace files available for replay; ctxdb uninstall --purge-logs removes them.

setup without --agent writes agents.default in ~/.ctxdb/ctxdb.json (CLI-only, no hooks or skills); with --agent <qoder|qoderwork|qwenwork|codex|claude|opencode|hermes> it writes agent config and installs hooks/plugins + skills for that harness. Rerunning it repairs integration artifacts and may replace the selected Agent's API key. 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 create/update completion mode

kb upload-text, kb upload-file, kb update-text, and kb update-file return as soon as the service accepts the document. The returned document may still have ingest_status: "processing"; acceptance does not mean ingestion succeeded.

• Add --wait when a script needs the previous behavior: poll until ingestion succeeds, fails, or reaches the existing command timeout.
• Existing --no-wait calls remain valid and behave like the new default.
• --wait and --no-wait cannot be combined.

Scripts that relied on implicit terminal polling must migrate to:

ctxdb kb upload-text <kb-name> <doc-name> --text="<body>" --wait
ctxdb kb upload-file <kb-name> <local-path> --wait
ctxdb kb update-text <document-id> --text="<body>" --wait
ctxdb kb update-file <document-id> <local-path> --wait

Explicit KB document updates

Create and update are separate operations. upload-text / upload-file use create-only POST routes, so an existing logical document produces HTTP 409 and is never silently overwritten. update-text / update-file use PUT and accept exactly one locator family: the canonical document ID (preferred), or an explicit knowledge-base name + logical document name + optional normalized --file-path.

# Preferred: no KB/name/path lookup or reconstruction
ctxdb kb update-text <document-id> --text="<new-body>"
ctxdb kb update-file <document-id> <local-path>

# Alternative when the exact document ID is unavailable
ctxdb kb update-text --kb-name=<kb-name> --doc-name=<logical-name> --text="<new-body>" [--file-path=<logical-parent>]
ctxdb kb update-file <local-path> --kb-name=<kb-name> [--doc-name=<existing-logical-name>] [--file-path=<logical-parent>]

Do not combine a positional document ID with --kb-name, --doc-name, or --file-path. ID mode derives the existing document's KB and logical metadata on the server; a replacement file's basename remains only its physical upload filename. Logical-key file mode defaults --doc-name to that basename, so pass the existing logical name when the replacement basename differs.

Every successful update returns the canonical document.id and document.knowledge_base_id. Changed content can replace the input ID, while same-content updates may reuse it. Callers must retain the returned ID for the next update; --wait also polls the returned ID/KB pair rather than caller input.

KB file upload policy and large files

kb upload-file and kb update-file do not maintain a client-side format allowlist or file-size table. It validates only that the local path exists, is a readable regular file, then lets the service decide whether the format, per-type size, quota, and logical document identity are acceptable. Unknown extensions are sent as application/octet-stream.

File bytes are streamed from disk with a known multipart size; the CLI does not read the complete file into a Buffer. Each command attempts its ordinary direct endpoint first. If the service returns the dedicated KNOWLEDGE_DIRECT_UPLOAD_REQUIRES_CHUNK error (errorCode=6001) or an unstructured HTTP 413, the CLI automatically uses the chunk init/part/complete protocol. Create init uses POST and update init uses PUT; parts, complete, and abort stay on POST. Document-ID update init sends the ID and physical filename without resolving a KB. Logical-key update init resolves the KB and sends the same KB/name/path identity as direct mode.

Chunk init and complete accept the release_pre bare response objects. Create also accepts the previous Box.data init/complete shape during rolling deployment; part and abort responses remain Box-wrapped. This response-shape compatibility does not fall back from logical-key PUT to an older update contract.

The first chunk-routing release intentionally sends init, each part, and complete only once. It does not automatically retry timeout, connection-loss, or response-loss failures because the service cannot yet prove that those operations are idempotent. Failures before complete trigger a best-effort abort; ambiguous complete failures are returned to the caller.

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.

Default and --verbose search output is graph-aware. Ordinary document evidence remains in chunks; a GraphRAG synthesis row is moved to the optional graph_context object and is explicitly non-citable:

{
  "graph_context": {
    "type": "graph_context",
    "content": "...",
    "knowledge_base_ids": ["kb-id"],
    "citation_eligible": false
  },
  "chunks": [{ "content": "direct document evidence", "score": 0.73 }],
  "total": 1
}

--verbose adds source fields to document chunks plus source_label / tags to graph context. --raw is unchanged and returns the server response verbatim, including the synthetic graph row inside chunks. Agents use graph context for relationship understanding and, only when direct evidence is missing, at most one layer of up to three targeted document searches; final claims and citations come from document chunks. A future server contract should expose an explicit graph result type and graph source document/chunk IDs so clients no longer need tag/label detection and can provide real provenance.

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": false,
      "recall_knowledge": false,
      "top_k": 5,
      "threshold": 0.4,
      "knowledge_top_k": 6,
      "debug": false
    },
    "qoderwork": { "...": "same schema, independent values" },
    "qwenwork": { "...": "same schema, independent values" },
    "codex": { "...": "same schema, independent values" },
    "claude": { "...": "same schema, independent values" },
    "opencode": { "...": "same schema, independent values" },
    "hermes": { "...": "same schema, independent values" }
  }
}

Agent selection is driven by --agent <qoder|qoderwork|qwenwork|codex|claude|opencode|hermes|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 | | agent_id | str | null | Optional scope dimension on every capture/recall call. Default null = not sent — the server counts agent_id as scope on the search path, so emitting it by default would narrow every existing user's recall. Set only when you want per-agent isolation: CTXDB_AGENT_ID=<id> (env-only; no setup flag) | | app_id | str | null | Optional app-scope dimension, same contract as agent_id (default null = not sent). Set via CTXDB_APP_ID=<id> (env-only) | | auto_capture | bool | true | End-of-turn hook/plugin 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 | false | SessionStart hook recalls cwd/git-related memories for the selected agent. Default is off — open it per-agent when you want session-start warmup (adds one bounded, circuit-protected recall call on session start) | | 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 | Configured preference for verbose hook logging and full recall tracing. Effective debug is forced on for every final base_url outside the exact official-production allowlist; see “Debug control and recall replay”. General logs go to ~/.ctxdb/logs/ctxdb.log, structured full-content recall records to ~/.ctxdb/logs/recall-trace.jsonl |

Env-var overrides apply to the selected agent config (env wins): CTXDB_AGENT / CTXDB_API_KEY / CTXDB_BASE_URL / CTXDB_USER_ID / CTXDB_AGENT_ID / CTXDB_APP_ID. The last two default to unset — the request body omits agent_id/app_id entirely; set them only when you want per-agent / per-app scope isolation on the server.

Hook/plugin escape hatch: set CTXDB_SKIP_HOOKS=TRUE on the agent process to make all ctxdb hook entrypoints exit immediately before reading config or calling the API. Direct ctxdb memory / ctxdb kb / ctxdb setup CLI commands are unchanged.

run_id is not env-driven: capture reads the host's session id from the lifecycle payload (Qoder / Codex / Claude Code and Hermes pass session_id; opencode reads ev.properties.sessionID) and sends it as run_id on capture only, so the server can associate turns within one session for richer extraction context. Recall stores that host value locally as trace session_id but never sends run_id. If the payload has no session id, trace replay remains possible by recall_event_id; capture omits run_id and proceeds normally (the server falls back to baseMessages).

Architecture

@aliyunrds/ctxdb            ← this package (CLI + setup + hooks + skills)
       │
       ├─ bundles OpenCode plugin (self-contained) in dist/opencode/index.js; setup copies it to ~/.config/opencode/plugins/ctxdb-bundle.js
       │
       └─ 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 qwenwork
ctxdb uninstall --agent codex
ctxdb uninstall --agent claude
ctxdb uninstall --agent opencode
ctxdb uninstall --agent hermes

# 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, ~/.qoderwork/settings.json, ~/.qwenwork/settings.json, ~/.codex/hooks.json, ~/.claude/settings.json, and ~/.hermes/config.yaml: 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