@aliyunrds/ctxdb 1.0.10 → 1.0.11-beta.0

package/README.md

@@ -9,7 +9,7 @@ Unified access layer for RDS ContextDatabase. One `ctxdb` CLI (memory + KB ops),
 | **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) |
+| **opencode** | Plugin bundle (`~/.config/opencode/plugins/ctxdb-bundle.js`) | `~/.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) |
 | **workbuddy** | ✅ UserPromptSubmit + Stop + SessionStart | `~/.workbuddy/skills/` and `~/.workbuddy-ai/skills/` (existing homes) | CodeBuddy command hooks (complete shell command, no separate `args`) |
 
@@ -309,7 +309,7 @@ ctxdb status --agent codex --json
 
 Setup first checks that the target agent home exists (`~/.qoder`, `~/.qoderwork`, `~/.qwenwork`, `~/.codex`, `~/.claude`, or either WorkBuddy home: `~/.workbuddy` / `~/.workbuddy-ai`; other declared CN variant homes also satisfy this check). Setup writes hooks and skills into every existing home, 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**, **claude**, and **workbuddy**, 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) — Current Codex versions enable hooks by default; the explicit setting also supports older installs. Review and trust each installed or changed hook definition in `/hooks` before use. 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.
+For **qoder**, **qoderwork**, **qwenwork**, **codex**, **claude**, and **workbuddy**, 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) — Current Codex versions enable hooks by default; the explicit setting also supports older installs. Review and trust each installed or changed hook definition in `/hooks` before use. For **opencode**, restart OpenCode so it loads `~/.config/opencode/plugins/ctxdb-bundle.js`. 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:
 
@@ -366,7 +366,7 @@ Implementation note: qoder/Claude/WorkBuddy consume the JSON `hookSpecificOutput
 
 WorkBuddy 5.5.2 on macOS requires the full shell command in `command`; its runner ignores `args`. Native Auto (default routing label; underlying model unknown) and explicitly selected GPT-5.6-Sol completed automatic Skill Evaluate, suggestion delivery, generation, Upload/Complete, and exact Load. The final package also passed cold-cache Load for both versions. Sol required one native Retry after a platform error; Auto's extra execution was not proven fully isolated. Windows runner behavior and Memory capture/recall were not tested in this acceptance run. See the [Agent/model acceptance report](../../docs/skill-agent-acceptance-20260912.md) and [WorkBuddy evidence](../../docs/workbuddy-acceptance-20260912.md) for version scope, retained failures, and cleanup.
 
-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 **opencode**, `ctxdb setup --agent opencode` copies the self-contained plugin bundle to `~/.config/opencode/plugins/ctxdb-bundle.js` as the single auto-loaded entry. Setup and `ctxdb upgrade --agent opencode` remove the older generated `ctxdb.ts` shim: OpenCode loads both `.ts` and `.js`, so keeping both files initializes the plugin twice. Run upgrade after updating the npm package, then restart OpenCode. An unrecognized `ctxdb.ts` is preserved and reported as a migration conflict.
 
 For **hermes**, `ctxdb setup --agent hermes` writes two shell hooks under `~/.hermes/config.yaml`:
 
@@ -443,6 +443,17 @@ fact-extraction). Use it when the user explicitly asks for a verbatim
 memory ("记住 / 请记忆 / 原文记下"); without `--no-infer` the server may
 rewrite, merge, or skip details.
 
+Memory uploads (`memory add`, including images, and automatic hook/plugin
+capture) always send a top-level `agent_id`. `CTXDB_AGENT_ID` takes precedence
+over the selected config's `agent_id`; when neither is set, uploads use the
+current Agent name (`--agent`, then `CTXDB_AGENT`, then `default`; OpenCode's
+plugin uses `opencode`). `default` means no specific host was selected.
+This fallback applies only to uploads: default search/list and automatic
+recall remain unchanged, so historical and other agents' memories can still
+be retrieved. An explicitly configured `agent_id` continues to filter
+automatic recall. The field records write attribution; server-side memory
+organization may still deduplicate facts across agents within one Member.
+
 `memory add [<text>] --image=<local-path>` adds an image-backed memory.
 Repeat `--image` to attach multiple PNG, JPEG, or WebP files; text is optional
 when at least one image is present. Image requests require inference, so they
@@ -861,8 +872,8 @@ 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) |
+| `agent_id` | str | null | Explicit memory upload attribution and automatic-recall filter. Uploads fall back to the current Agent name; automatic recall omits this filter unless explicitly configured. `CTXDB_AGENT_ID=<id>` overrides this value (no setup flag). This does not guarantee per-agent retention during server-side deduplication. |
+| `app_id` | str | null | Optional app-scope dimension for automatic capture/recall; default null means 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_skill_evolution` | bool | `true` | Evidence collection and automatic evolution through the selected Agent hooks/plugin. Hermes delivers ready suggestions on the next genuine user turn. Disabling it keeps private Skill discovery and explicit commands available. |
 | `auto_recall` | bool | `true` | UserPromptSubmit hook recalls memory on each user prompt for the selected agent |
@@ -872,7 +883,7 @@ Field reference:
 | `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_ACCESS_TOKEN` / `CTXDB_API_KEY` / `CTXDB_BASE_URL` / `CTXDB_USER_ID` / `CTXDB_AGENT_ID` / `CTXDB_APP_ID`. The internal login command additionally reads `CTXDB_LOGIN_SERVER` as its provider-neutral login endpoint. 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.
+Env-var overrides apply to the selected agent config (env wins): `CTXDB_AGENT` / `CTXDB_ACCESS_TOKEN` / `CTXDB_API_KEY` / `CTXDB_BASE_URL` / `CTXDB_USER_ID` / `CTXDB_AGENT_ID` / `CTXDB_APP_ID`. The internal login command additionally reads `CTXDB_LOGIN_SERVER` as its provider-neutral login endpoint. The last two default to unset: automatic recall omits both filters, while uploads still send the current Agent name as `agent_id`.
 
 Downstream Agent hosts can set `CTXDB_ACCESS_TOKEN` to send `Authorization: Bearer <token>` to the Data API. It is runtime-only, never written to `~/.ctxdb/ctxdb.json`, and takes precedence over a managed session or API key for CLI, process hooks, and OpenCode; a rejected token does not fall back to another credential. `ctxdb setup` can use a managed reference or an environment AT for validation, but never persists the AT. An environment-only credential must remain available to the Agent runtime after setup.
 
@@ -903,7 +914,7 @@ Two npm packages total. `@aliyunrds/ctxdb-shared` stays separate because OpenCla
 
 ```sh
 # 1. Strip hooks + skills + (optionally) config + logs while the binary still works.
-ctxdb uninstall --purge-all     # everything: hooks, skills, ~/.ctxdb/ctxdb.json, ~/.ctxdb/logs/
+ctxdb uninstall --purge-all     # hooks, skills, and all ctxdb-owned local state
 
 # 2. Then drop the npm binaries.
 npm uninstall -g @aliyunrds/ctxdb @aliyunrds/ctxdb-shared
@@ -911,6 +922,8 @@ 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.
 
+Stop running Agent sessions and transfers before purging. `--purge-all` deletes the shared credential store (public and internal logins), cache, sessions, and Skill state including local drafts. It preserves and reports unknown files. Local deletion does not revoke server sessions: log out of each login before uninstalling if you want to revoke them. Purge flags cannot be combined with `--agent`; that combination fails before changing any files.
+
 ### Partial removal
 
 ```sh
@@ -937,7 +950,8 @@ ctxdb uninstall --purge-logs     # also deletes ~/.ctxdb/logs/
 
 - **Hook entries in `~/.qoder/settings.json`, `~/.qoderwork/settings.json`, `~/.qwenwork/settings.json`, `~/.codex/hooks.json`, `~/.claude/settings.json`, `~/.workbuddy/settings.json`, `~/.workbuddy-ai/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).
+- **Hermes hook approvals**: removes ctxdb event/command entries from `~/.hermes/shell-hooks-allowlist.json`, preserving other approvals and metadata.
+- **`~/.ctxdb/` state**: only with `--purge-config` / `--purge-logs` / `--purge-all`. Full purge removes `ctxdb.json`, `ctxdb.json.bak`, `credentials.json`, `logs`, `cache`, `circuit`, `sessions`, `skills`, `skill-evolution`, and interrupted config/credential writes. Unknown paths are preserved and listed; the root is removed when empty. Symlink targets are never recursively deleted. Deletion errors return a nonzero exit status and suppress the npm-uninstall hint so the cleanup can be retried.
 - **`~/.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.
 

package/dist/{chunk-5HPYYOPH.js → chunk-6XK3RDZ6.js}

@@ -2,7 +2,7 @@
 import {
   fetchKbCatalogBlock,
   recallTurn
-} from "./chunk-VMBCSFGF.js";
+} from "./chunk-XEX5344F.js";
 
 // src/lib/user-prompt-submit-compose.ts
 async function composeUserPromptSubmit(cfg, agent, client, prompt, sessionId = null) {

package/dist/{chunk-XWJAZAMN.js → chunk-7RMETV4M.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   configDir
-} from "./chunk-TZFDXKLJ.js";
+} from "./chunk-HHKQPWYI.js";
 
 // src/lib/circuit.ts
 import { statSync, writeFileSync, unlinkSync, mkdirSync, readdirSync, readFileSync } from "node:fs";

package/dist/{chunk-LASAMQQY.js → chunk-EWCB3UQS.js}

@@ -4,7 +4,10 @@ import {
   isConnectionError,
   resetCircuit,
   tripCircuit
-} from "./chunk-XWJAZAMN.js";
+} from "./chunk-7RMETV4M.js";
+import {
+  resolveMemoryUploadAgentId
+} from "./chunk-SR3M7AL5.js";
 import {
   CtxdbError,
   debug,
@@ -15,7 +18,7 @@ import {
   selectTurnRows,
   toKbDetectionMessages,
   toParsedMessages
-} from "./chunk-TZFDXKLJ.js";
+} from "./chunk-HHKQPWYI.js";
 
 // src/lib/capture-orchestrator.ts
 import {
@@ -117,9 +120,9 @@ async function captureParsedMessages(parsed, cfg, client, agent = "default", ses
   const payload = {
     messages,
     user_id: cfg.userId,
+    agent_id: resolveMemoryUploadAgentId(cfg.agentId, agent),
     async_mode: true
   };
-  if (cfg.agentId) payload.agent_id = cfg.agentId;
   if (cfg.appId) payload.app_id = cfg.appId;
   if (sessionId) payload.run_id = sessionId;
   let resp;

package/dist/{chunk-QUPLZ7KF.js → chunk-G3MDJEX5.js}

@@ -429,7 +429,7 @@ function shouldUseUpdateNotifier(argv, options = {}) {
     return false;
   }
   const command = argv[0];
-  return command !== "update" && command !== "upgrade";
+  return !["update", "upgrade", "uninstall", "teardown"].includes(command);
 }
 function beginUpdateNotification(argv, options) {
   try {