@aliyunrds/ctxdb 0.0.7 → 0.0.8-beta.1

package/dist/{chunk-LIC44DR6.js → chunk-C62I23HL.js}

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
+import {
+  listKnowledgeBases
+} from "./chunk-6S5RJYBC.js";
 import {
   isConnectionError,
   resetCircuit,
   tripCircuit
-} from "./chunk-Q2EEP4CE.js";
+} from "./chunk-KEQMJ6IO.js";
 import {
   CtxdbError
-} from "./chunk-S45GOYUU.js";
+} from "./chunk-U3T5O6NX.js";
 
 // src/lib/recall-orchestrator.ts
 import {
@@ -138,6 +141,34 @@ async function recallTurn(prompt, cfg, client, agent = "default") {
   };
 }
 
+// src/lib/kb-catalog.ts
+function sanitizeKeyEntities(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const e of raw) {
+    if (typeof e !== "string") continue;
+    const cleaned = e.replace(/\s+/g, " ").trim();
+    if (cleaned.length > 0) out.push(cleaned);
+  }
+  return out;
+}
+async function fetchKbCatalogBlock(client, agent) {
+  const kbs = await listKnowledgeBases(client);
+  const active = kbs.filter((kb) => kb.status === "active");
+  if (active.length === 0) return "";
+  const lines = active.map((kb) => {
+    const ents = sanitizeKeyEntities(kb.key_entities);
+    return ents.length > 0 ? `\xB7 ${kb.name}: ${ents.join(", ")}` : `\xB7 ${kb.name}`;
+  });
+  return [
+    "<available-knowledge-bases>",
+    `When you identify that relevant information may exist in the knowledge bases below, you MUST run \`ctxdb kb search "<query>" --kb=<name> --agent=${agent}\` with targeted keywords after initial analysis to supplement and correct your approach. Knowledge bases:`,
+    ...lines,
+    "</available-knowledge-bases>"
+  ].join("\n");
+}
+
 export {
-  recallTurn
+  recallTurn,
+  fetchKbCatalogBlock
 };

package/dist/{chunk-Q2EEP4CE.js → chunk-KEQMJ6IO.js}

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

package/dist/{chunk-S45GOYUU.js → chunk-U3T5O6NX.js}

@@ -308,6 +308,7 @@ var DEFAULT_USER_ID = "default";
 var DEFAULT_TOP_K = 5;
 var DEFAULT_THRESHOLD = 0.4;
 var DEFAULT_KNOWLEDGE_TOP_K = 6;
+var DEFAULT_KB_CATALOG_INJECTION = "session_start";
 function isComplete(cfg) {
   return Boolean(cfg.apiKey && cfg.baseUrl);
 }
@@ -330,6 +331,12 @@ function coerceBool(v, fallback) {
   if (v === void 0 || v === null) return fallback;
   return Boolean(v);
 }
+function coerceKbCatalogInjection(v) {
+  if (v === "session_start" || v === "user_prompt_submit" || v === "off") {
+    return v;
+  }
+  return DEFAULT_KB_CATALOG_INJECTION;
+}
 function readRaw(path) {
   if (!existsSync(path)) return {};
   try {
@@ -367,7 +374,8 @@ function configFromDisk(raw) {
     topK: coerceInt(raw.top_k, DEFAULT_TOP_K),
     threshold: coerceFloat(raw.threshold, DEFAULT_THRESHOLD),
     knowledgeTopK: coerceInt(raw.knowledge_top_k, DEFAULT_KNOWLEDGE_TOP_K),
-    debug: coerceBool(raw.debug, false)
+    debug: coerceBool(raw.debug, false),
+    kbCatalogInjection: coerceKbCatalogInjection(raw.kb_catalog_injection)
   };
 }
 function applyEnv(cfg, env) {
@@ -416,7 +424,8 @@ function configToDisk(cfg) {
     top_k: cfg.topK,
     threshold: cfg.threshold,
     knowledge_top_k: cfg.knowledgeTopK,
-    debug: cfg.debug
+    debug: cfg.debug,
+    kb_catalog_injection: cfg.kbCatalogInjection
   };
 }
 function removeAgent(agent, path, options = {}) {

package/dist/cli/main.js

@@ -29,7 +29,7 @@ import {
   removeAgent,
   save,
   writeInstalledPkgVersion
-} from "../chunk-S45GOYUU.js";
+} from "../chunk-U3T5O6NX.js";
 
 // src/cli/util.ts
 var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
@@ -624,11 +624,15 @@ function checkHookNodePaths(agent) {
       if (!entryIsCtxdb(entry)) continue;
       for (const h of entry.hooks ?? []) {
         if (h?.type !== "command" || typeof h.command !== "string") continue;
-        const cmd = h.command;
-        if (cmd.includes("@aliyunrds/ctxdb")) {
-          const parts = cmd.split(" ");
-          if (parts.length >= 2 && !parts[0].endsWith(".js") && !parts[0].endsWith(".ts")) {
-            nodePaths.add(parts[0]);
+        if (Array.isArray(h.args) && h.args.length > 0) {
+          nodePaths.add(h.command);
+        } else {
+          const cmd = h.command;
+          if (cmd.includes("@aliyunrds/ctxdb")) {
+            const parts = cmd.split(" ");
+            if (parts.length >= 2 && !parts[0].endsWith(".js") && !parts[0].endsWith(".ts")) {
+              nodePaths.add(parts[0]);
+            }
           }
         }
       }
@@ -865,16 +869,15 @@ var LEGACY_MARKER_KEYS = ["_ctxdbQoder", "_ctxdbPackage"];
 var LEGACY_MARKER_VALUES = ["@aliyunrds/ctxdb-qoder"];
 var TOOL_SCOPED_EVENTS = /* @__PURE__ */ new Set(["PreToolUse", "PostToolUse"]);
 function appendOne(hooks, event, command, agent) {
-  const commandWithAgent = `${process.execPath} ${command} --agent=${agent}`;
   if (!Array.isArray(hooks[event])) hooks[event] = [];
   const dup = hooks[event].some(
     (entry2) => Array.isArray(entry2?.hooks) && entry2.hooks.some(
-      (h) => h?.type === "command" && typeof h.command === "string" && h.command === commandWithAgent
+      (h) => h?.type === "command" && Array.isArray(h.args) && h.args[0] === command
     )
   );
   if (dup) return;
   const entry = {
-    hooks: [{ type: "command", command: commandWithAgent, timeout: 60 }],
+    hooks: [{ type: "command", command: process.execPath, args: [command, `--agent=${agent}`], timeout: 60 }],
     [ENTRY_MARKER_KEY]: ENTRY_MARKER_VALUE,
     [ENTRY_AGENT_KEY]: agent
   };

package/dist/hooks/session-start.js

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 import {
+  fetchKbCatalogBlock,
   recallTurn
-} from "../chunk-LIC44DR6.js";
+} from "../chunk-C62I23HL.js";
+import "../chunk-6S5RJYBC.js";
 import {
   isCircuitOpen
-} from "../chunk-Q2EEP4CE.js";
+} from "../chunk-KEQMJ6IO.js";
 import {
   HttpClient,
   agentFromArgvWithFallback,
@@ -12,7 +14,10 @@ import {
   isComplete,
   load,
   setDebug
-} from "../chunk-S45GOYUU.js";
+} from "../chunk-U3T5O6NX.js";
+
+// src/hooks/session-start.ts
+import { pathToFileURL } from "url";
 
 // src/lib/warmup-recall.ts
 import { execSync } from "child_process";
@@ -67,6 +72,41 @@ async function warmupRecall(cwd, cfg, client) {
 
 // src/hooks/session-start.ts
 var HOOK_TIMEOUT_MS = 5e3;
+function timeout(ms) {
+  return new Promise((resolve) => setTimeout(() => resolve(null), ms));
+}
+async function composeSessionStart(cfg, agent, client, cwd, timeoutMs = HOOK_TIMEOUT_MS) {
+  const kbInjectHere = cfg.kbCatalogInjection === "session_start";
+  const warmupPromise = cfg.warmupRecall ? Promise.race([warmupRecall(cwd, cfg, client), timeout(timeoutMs).then(() => null)]) : Promise.resolve(null);
+  const kbPromise = kbInjectHere ? Promise.race([fetchKbCatalogBlock(client, agent).catch(() => ""), timeout(timeoutMs).then(() => "")]) : Promise.resolve("");
+  const [result, kbBlock] = await Promise.all([warmupPromise, kbPromise]);
+  const warmupTimedOut = cfg.warmupRecall && result === null;
+  const warmupCtx = result && result.ok ? result.additionalContext || "" : "";
+  if (!warmupCtx && result && !result.ok) {
+    debug("warmup", `no result: ${result.reason}`);
+  }
+  let ctx = warmupCtx;
+  if (kbBlock) ctx = ctx ? `${ctx}
+
+${kbBlock}` : kbBlock;
+  return {
+    ctx,
+    memoryCount: result?.ok ? result.memoryCount : 0,
+    kbChunkCount: result?.ok ? result.knowledgeChunkCount : 0,
+    kbCatalogLines: kbBlock ? kbBlock.split("\n").length : 0,
+    warmupTimedOut
+  };
+}
+function formatSessionStartStdout(agent, ctx) {
+  if (agent === "codex") return ctx + "\n";
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: ctx
+    }
+  };
+  return JSON.stringify(out) + "\n";
+}
 async function readStdinJson() {
   let raw = "";
   for await (const chunk of process.stdin) raw += chunk;
@@ -78,9 +118,6 @@ async function readStdinJson() {
     return {};
   }
 }
-function timeout(ms) {
-  return new Promise((resolve) => setTimeout(() => resolve(null), ms));
-}
 async function main() {
   try {
     const event = await readStdinJson();
@@ -96,8 +133,9 @@ async function main() {
     const cfg = load({ agent });
     setDebug(cfg.debug);
     debug("warmup", "start", { cwd, userId: cfg.userId });
-    if (!isComplete(cfg) || !cfg.warmupRecall) {
-      debug("warmup", "skip (config incomplete or warmupRecall=false)");
+    const kbInjectHere = cfg.kbCatalogInjection === "session_start";
+    if (!isComplete(cfg) || !cfg.warmupRecall && !kbInjectHere) {
+      debug("warmup", "skip (config incomplete or both warmup+kb off)");
       return 0;
     }
     if (isCircuitOpen(agent, cfg.baseUrl)) {
@@ -109,34 +147,21 @@ async function main() {
       apiKey: cfg.apiKey,
       timeoutMs: HOOK_TIMEOUT_MS
     });
-    const result = await Promise.race([
-      warmupRecall(cwd, cfg, client),
-      timeout(HOOK_TIMEOUT_MS).then(() => null)
-    ]);
-    if (!result) {
+    const composed = await composeSessionStart(cfg, agent, client, cwd);
+    if (composed.warmupTimedOut) {
       process.stderr.write("ctxdb warmup: timeout\n");
-      return 0;
     }
-    if (!result.ok || !result.additionalContext) {
-      debug("warmup", `no result: ${result.reason}`);
-      return 0;
-    }
-    debug("warmup", `ok, memories=${result.memoryCount} kb=${result.knowledgeChunkCount}`);
+    if (!composed.ctx) return 0;
+    const { memoryCount, kbChunkCount, kbCatalogLines, ctx } = composed;
+    debug(
+      "warmup",
+      `ok, memories=${memoryCount} kb=${kbChunkCount} kb_catalog=${kbCatalogLines}`
+    );
     process.stderr.write(
-      `ctxdb warmup: ok (${result.memoryCount} memories, ${result.knowledgeChunkCount} kb chunks)
+      `ctxdb warmup: ok (${memoryCount} memories, ${kbChunkCount} kb chunks, kb_catalog=${kbCatalogLines} lines)
 `
     );
-    if (agent === "codex") {
-      process.stdout.write(result.additionalContext + "\n");
-    } else {
-      const out = {
-        hookSpecificOutput: {
-          hookEventName: "SessionStart",
-          additionalContext: result.additionalContext
-        }
-      };
-      process.stdout.write(JSON.stringify(out) + "\n");
-    }
+    process.stdout.write(formatSessionStartStdout(agent, ctx));
     return 0;
   } catch (err) {
     process.stderr.write(`ctxdb warmup: unexpected error: ${err?.message ?? err}
@@ -144,4 +169,11 @@ async function main() {
     return 0;
   }
 }
-main().then((code) => process.exit(code));
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  main().then((code) => process.exit(code));
+}
+export {
+  HOOK_TIMEOUT_MS,
+  composeSessionStart,
+  formatSessionStartStdout
+};

package/dist/hooks/stop.js

@@ -4,7 +4,7 @@ import {
   isConnectionError,
   resetCircuit,
   tripCircuit
-} from "../chunk-Q2EEP4CE.js";
+} from "../chunk-KEQMJ6IO.js";
 import {
   CtxdbError,
   HttpClient,
@@ -12,7 +12,7 @@ import {
   debug,
   load,
   setDebug
-} from "../chunk-S45GOYUU.js";
+} from "../chunk-U3T5O6NX.js";
 
 // src/lib/capture-orchestrator.ts
 import {
@@ -32,7 +32,7 @@ function getGitContext() {
     }).trim();
     const lines = raw.split("\n");
     if (lines.length < 2) return null;
-    const project = lines[0].split("/").pop();
+    const project = lines[0].split(/[/\\]/).pop();
     if (!project) return null;
     const branch = lines[1];
     return { project, branch };
@@ -305,18 +305,12 @@ async function captureTurn(transcriptPath, cfg, client, agent = "default") {
   }
   const git = getGitContext();
   const skills = extractSkillSignals(rows);
-  const bgParts = [];
-  if (git) {
-    bgParts.push(`This conversation took place in project "${git.project}", branch "${git.branch}".`);
-  }
-  if (skills.length > 0) {
-    const descs = skills.map((s) => {
-      const label = s.trigger === "command" ? "user-invoked" : "agent-invoked";
-      return s.args ? `${s.skill} (${label}, args: "${s.args}")` : `${s.skill} (${label})`;
-    });
-    bgParts.push(`Skills used: ${descs.join(", ")}.`);
-  }
-  const messages = bgParts.length > 0 ? [{ role: "background", content: bgParts.join("\n") }, ...filtered] : filtered;
+  const bg = {};
+  if (git) bg.git = git;
+  if (skills.length > 0) bg.skills = skills.map(
+    ({ skill, trigger, args }) => args ? { skill, trigger, args } : { skill, trigger }
+  );
+  const messages = bg.git || bg.skills ? [{ role: "background", content: JSON.stringify(bg) }, ...filtered] : filtered;
   const payload = {
     messages,
     user_id: cfg.userId,

package/dist/hooks/user-prompt-submit.js

@@ -1,13 +1,12 @@
 #!/usr/bin/env node
 import {
-  listKnowledgeBases
-} from "../chunk-6S5RJYBC.js";
-import {
+  fetchKbCatalogBlock,
   recallTurn
-} from "../chunk-LIC44DR6.js";
+} from "../chunk-C62I23HL.js";
+import "../chunk-6S5RJYBC.js";
 import {
   isCircuitOpen
-} from "../chunk-Q2EEP4CE.js";
+} from "../chunk-KEQMJ6IO.js";
 import {
   HttpClient,
   agentFromArgvWithFallback,
@@ -15,23 +14,31 @@ import {
   isComplete,
   load,
   setDebug
-} from "../chunk-S45GOYUU.js";
-
-// src/lib/kb-catalog.ts
-async function fetchKbCatalogBlock(client, agent) {
-  const kbs = await listKnowledgeBases(client);
-  const active = kbs.filter((kb) => kb.status === "active");
-  if (active.length === 0) return "";
-  const lines = active.map((kb) => `\xB7 ${kb.name}`);
-  return [
-    "<available-knowledge-bases>",
-    `When you identify that relevant information may exist in the knowledge bases below, you MUST run \`ctxdb kb search "<query>" --kb=<name> --agent=${agent}\` with targeted keywords after initial analysis to supplement and correct your approach. Knowledge bases:`,
-    ...lines,
-    "</available-knowledge-bases>"
-  ].join("\n");
-}
+} from "../chunk-U3T5O6NX.js";
 
 // src/hooks/user-prompt-submit.ts
+import { pathToFileURL } from "url";
+async function composeUserPromptSubmit(cfg, agent, client, prompt) {
+  const [recall, kbBlock] = await Promise.all([
+    recallTurn(prompt, cfg, client, agent),
+    cfg.kbCatalogInjection === "user_prompt_submit" ? fetchKbCatalogBlock(client, agent).catch(() => "") : Promise.resolve("")
+  ]);
+  let ctx = recall.additionalContext || "";
+  if (kbBlock) ctx = ctx ? `${ctx}
+
+${kbBlock}` : kbBlock;
+  return { ctx, recall, kbBlock };
+}
+function formatUserPromptSubmitStdout(agent, ctx) {
+  if (agent === "codex") return ctx + "\n";
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: "UserPromptSubmit",
+      additionalContext: ctx
+    }
+  };
+  return JSON.stringify(out) + "\n";
+}
 async function readStdinJson() {
   let raw = "";
   for await (const chunk of process.stdin) raw += chunk;
@@ -69,36 +76,19 @@ async function main() {
       return 0;
     }
     const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey, timeoutMs: 5e3 });
-    const [result, kbBlock] = await Promise.all([
-      recallTurn(prompt, cfg, client, agent),
-      fetchKbCatalogBlock(client, agent).catch(() => "")
-    ]);
-    if (!result.ok && !result.additionalContext && !kbBlock) {
-      const reason = result.reason ?? "no_context";
-      debug("recall", `no result: ${reason}`, result);
-      if (result.reason && result.reason.startsWith("http_error:")) {
-        process.stderr.write(`ctxdb recall: ${result.reason}
+    const { ctx, recall, kbBlock } = await composeUserPromptSubmit(cfg, agent, client, prompt);
+    if (!recall.ok && !recall.additionalContext && !kbBlock) {
+      const reason = recall.reason ?? "no_context";
+      debug("recall", `no result: ${reason}`, recall);
+      if (recall.reason && recall.reason.startsWith("http_error:")) {
+        process.stderr.write(`ctxdb recall: ${recall.reason}
 `);
       }
       return 0;
     }
-    let ctx = result.additionalContext || "";
-    if (kbBlock) ctx = ctx ? `${ctx}
-
-${kbBlock}` : kbBlock;
     if (!ctx) return 0;
     debug("recall", `ok, additionalContext length=${ctx.length}`);
-    if (agent === "codex") {
-      process.stdout.write(ctx + "\n");
-    } else {
-      const out = {
-        hookSpecificOutput: {
-          hookEventName: "UserPromptSubmit",
-          additionalContext: ctx
-        }
-      };
-      process.stdout.write(JSON.stringify(out) + "\n");
-    }
+    process.stdout.write(formatUserPromptSubmitStdout(agent, ctx));
     return 0;
   } catch (err) {
     process.stderr.write(`ctxdb recall: unexpected error: ${err?.message ?? err}
@@ -106,4 +96,10 @@ ${kbBlock}` : kbBlock;
     return 0;
   }
 }
-main().then((code) => process.exit(code));
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  main().then((code) => process.exit(code));
+}
+export {
+  composeUserPromptSubmit,
+  formatUserPromptSubmitStdout
+};

package/dist/setup/skills/contextdb-knowledge/SKILL.md

@@ -1,161 +1,189 @@
 ---
 name: contextdb-knowledge
-description: RDS contextdb 知识库操作全量参考。覆盖 kb create / search / upload-text / upload-file / list / documents-list / document-get 的完整参数和 JSON 输出结构。当用户提到"查知识库"、"查 KB"、"上传到 KB"、"灌进知识库"、"列出知识库"、"看文档"、"建知识库"等场景时使用。
+description: contextdb 知识库高频操作（查询 / 浏览 KB / 上传文档）和命令速查。当用户提到"查知识库 / 查 KB / 搜知识库 / 查 KB chunks / 上传到 KB / 灌进知识库 / 列出知识库 / 列出 KB / 看文档 / 建知识库 / 建 KB"等场景时使用。配套 contextdb-memory 处理长期记忆。
 ---
 
-# contextdb Knowledge Base 操作参考
+# contextdb Knowledge Base 操作
 
-## 配置
+## 1. 什么时候用这个 skill
 
-- 配置文件：`~/.ctxdb/ctxdb.json`
-- 配置命令：`ctxdb setup --api-key=<key> --base-url=<url> [--user-id=<id>]`
-- 带 `--agent <name>` 时写入指定 agent 的配置段并安装 hooks + skill
-- 不带 `--agent` 时写入 `agents.default` 配置段（仅 CLI 使用）
-- 连接检查：`ctxdb ping`，状态查看：`ctxdb status`
+用户在做"查/灌/列知识库"的任何动作时进这个 skill。触发关键词：**查知识库 / 查 KB / 搜知识库 / 查 KB chunks / 上传到 KB / 灌进知识库 / 列出知识库 / 列出 KB / 看文档 / 建知识库**。
 
-## kb search
+- 用户想**找已有 KB 里的内容** → §2 recipe 1
+- 用户**不知道有哪些 KB** → §2 recipe 2
+- 用户想**了解某个 KB 收了哪些文档** → §2 recipe 3
+- 用户要**写入/上传内容** → §2 recipe 4/5
 
-搜索知识库。
+配套 skill：**contextdb-memory**（长期记忆操作）。两者用同一份 `~/.ctxdb/ctxdb.json` 配置和同一个 `--agent` 路由。
+
+## 2. 高频 recipes
+
+> 命令里 `--agent=qoder` 是必填参数。如果用户跑别的 agent（codex / claude），把 `qoder` 替换成对应名字。
+
+### Recipe 1：在已知 KB 中查内容（最常见）
+
+**场景**：用户问"X KB 里关于 Y 的内容"、"在知识库 Z 查一下 W"。
 
 ```sh
-ctxdb kb search "<query>" [--kb=<name1,name2>] [--top-k=N] [--threshold=F] [--verbose] [--raw] [--agent=<name>]
+ctxdb kb search "<query>" --kb=<kb-name> --top-k=6 --agent=qoder
 ```
 
-| 参数 | 说明 | 默认值 |
-|------|------|--------|
-| `<query>` | 搜索文本（必填） | |
-| `--kb` | 指定搜索的知识库名称，逗号分隔 | 搜索所有 KB |
-| `--top-k` | 返回 chunk 数上限 | 6 |
-| `--threshold` | 相关度阈值 | 0.4 |
-| `--verbose` | 每个 chunk 增加 `doc_name` / `kb_id` / `doc_id` / `tags` 字段 | false |
-| `--raw` | 服务端原始响应（13+ 字段，含 tokenizer 细节） | false |
-| `--agent` | 指定操作哪个 agent 的配置 | agents.default |
-
-**输出 JSON 结构**（默认）：
-
-```json
-{
-  "chunks": [
-    {
-      "content": "chunk 文本内容",
-      "score": 0.82
-    }
-  ]
-}
-```
+返回 `chunks` 数组，按 `score` 倒序判断相关性；默认 threshold 0.4，空结果时见 §5 注意事项 4。
 
-`--verbose` 模式增加字段：
-
-```json
-{
-  "chunks": [
-    {
-      "content": "chunk 文本内容",
-      "score": 0.82,
-      "doc_name": "zircodb-overview",
-      "kb_id": "kb-uuid",
-      "doc_id": "doc-uuid",
-      "tags": ["architecture"]
-    }
-  ]
-}
-```
+**何时不适用**：用户没指定 KB → 先走 recipe 2 列出来确认。
 
-## kb create
+### Recipe 2：列出所有 KB（不知道有哪些）
 
-创建知识库。
+**场景**：用户问"有哪些知识库"、"列一下 KB"，或本身在写 recipe 1 之前需要确认 KB 名。
 
 ```sh
-ctxdb kb create <kb-name> [--description=<desc>] [--agent=<name>]
+ctxdb kb list --agent=qoder
 ```
 
-| 参数 | 说明 |
-|------|------|
-| `<kb-name>` | 知识库名称（必填） |
-| `--description` | 知识库描述 |
+返回 `knowledge_bases` 数组，每项含 `name` / `id` / `document_count`。跨多 KB 查 chunk 时把 `name` 拼起来：`--kb=a,b,c`。
 
-上传前须先创建 KB。`upload-text` / `upload-file` 不会自动创建 KB，KB 不存在时会报错。
+**何时不适用**：hook 已注入 `<available-knowledge-bases>` 块时，直接读那个块更省一次调用（见 §4）。
 
-## kb upload-file
+### Recipe 3：列出某 KB 的文档清单
 
-上传本地文件到知识库。
+**场景**：用户问"X KB 收了哪些文档"、"X KB 里有几篇"。
 
 ```sh
-ctxdb kb upload-file <kb-name> <local-path> [--doc-name=<name>] [--file-path=<server-logical-path>] [--no-wait] [--agent=<name>]
+ctxdb kb documents-list <kb-name> --agent=qoder
 ```
 
-| 参数 | 说明 |
-|------|------|
-| `<kb-name>` | 目标知识库名称（须已存在） |
-| `<local-path>` | 本机文件路径 |
-| `--doc-name` | 服务端文档名（默认取文件名） |
-| `--file-path` | 服务端逻辑路径（归档/分类用） |
-| `--no-wait` | 不等待 chunking 完成，立即返回 |
+返回 `documents` 数组，每项含 `name` / `id` / `size`。
 
-支持格式：PDF、DOCX、MD、TXT。
+**何时不适用**：用户要的是文档**正文**而不是清单 → 走 recipe 1 用 `kb search`（见 §5 注意事项 1）。
 
-## kb upload-text
+### Recipe 4：灌一段文字进 KB
 
-上传文本内容到知识库。
+**场景**：用户说"把这段记进 X KB"、"上传这段文字到知识库 Y"。
 
 ```sh
-ctxdb kb upload-text <kb-name> <doc-name> --text="<body>" [--file-path=<server-logical-path>] [--no-wait] [--agent=<name>]
+ctxdb kb upload-text <kb-name> <doc-name> --text="<body>" --agent=qoder
 ```
 
-| 参数 | 说明 |
-|------|------|
-| `<kb-name>` | 目标知识库名称（须已存在） |
-| `<doc-name>` | 文档名称 |
-| `--text` | 文本内容（必填） |
-| `--file-path` | 服务端逻辑路径 |
-| `--no-wait` | 不等待 chunking 完成 |
+副作用操作。**用户没明示 KB 名前先 recipe 2 列出来确认**（见 §5 注意事项 3）。KB 不存在会直接报错，不自动创建。
 
-## kb list
+**何时不适用**：内容是本地文件 → recipe 5。
 
-列出所有知识库。
+### Recipe 5：上传本地文件到 KB
+
+**场景**：用户说"把 X.pdf 上传到 Y KB"、"灌这个文件进知识库 Z"。
 
 ```sh
-ctxdb kb list [--agent=<name>]
+ctxdb kb upload-file <kb-name> <local-path> --agent=qoder
 ```
 
-返回 `knowledge_bases` 数组，每项含知识库名称、ID、文档数等。
+支持格式：PDF / DOCX / MD / TXT。默认等待 chunking 完成；想立即返回加 `--no-wait`（见 §6）。
 
-## kb documents-list
+**何时不适用**：要上传的内容是字符串而非本地文件 → recipe 4。
 
-列出知识库中的文档。
+## 3. 命令速查
 
-```sh
-ctxdb kb documents-list <kb-name> [--agent=<name>]
-```
+`--agent=<name>` 必填；详细解析链见 §6。其他 advanced flag 见 §6。
 
-## kb document-get
+| 子命令 | minimal signature |
+|---|---|
+| `kb search` | `ctxdb kb search "<query>" --agent=<name>` |
+| `kb list` | `ctxdb kb list --agent=<name>` |
+| `kb documents-list` | `ctxdb kb documents-list <kb-name> --agent=<name>` |
+| `kb document-get` | `ctxdb kb document-get <kb-name> <doc-id> --agent=<name>` |
+| `kb create` | `ctxdb kb create <kb-name> --agent=<name>` |
+| `kb upload-text` | `ctxdb kb upload-text <kb-name> <doc-name> --text="<body>" --agent=<name>` |
+| `kb upload-file` | `ctxdb kb upload-file <kb-name> <local-path> --agent=<name>` |
 
-查看文档详情。
+所有命令 JSON 写 stdout、错误写 stderr 非零退出码。
 
-```sh
-ctxdb kb document-get <kb-name> <doc-id> [--agent=<name>]
-```
+## 4. Hooks 感知
+
+**`<available-knowledge-bases>` 块**：UPS / SessionStart hook 注入到 system context；存在时直接列出 workspace 内所有 KB 名（省一次 `kb list` 调用）。可直接喂给 `--kb=<name>`。
+
+**`<recalled-memories>` 块**：是 contextdb-memory 的产物，但 `kb search --knowledge` 会复用同样的 retrieval 路径。两块独立。
+
+**B-3c 守卫**：含 `kb upload-text` / `kb upload-file` 的对话轮次，其内容**不会**被 autoCapture 写入记忆（防文档原文混进记忆桶）。
+
+**纯 CLI 模式**：对话里没有上面任何块 → 说明当前不在 hook 环境（agent 是裸 CLI 调用），所有信息只能主动调命令拿。
 
-## 写操作注意事项
+## 5. 注意事项
 
-`kb create`、`kb upload-text`、`kb upload-file` 是副作用操作（创建 KB / 写入文档）。执行前须明确目标 KB 名称：
+### 注意事项 1：`kb document-get` 只返 metadata，**不返正文**
 
-- 用户指定了 KB 名称 → 直接使用
-- 用户未指定 → 先用 `kb list` 查看现有知识库，向用户确认目标 KB 后再操作
-- KB 不存在时 upload 命令会自动创建，需确认用户意图是新建还是写入已有 KB
+- **现象**：想读文档内容，调 `kb document-get` 拿到的只有 `{id, name, size, upload_time, tags}`，没 `content` 字段
+- **根因**：服务端当前只暴露元信息端点；获取正文需走 chunk 检索
+- **正确做法**：用 `kb search "<关键词>" --kb=<name>` 拿 chunks，或 `kb documents-list <kb-name>` 后浏览返回的内嵌 chunk（如有）
 
-## --agent 参数
+### 注意事项 2：解析 JSON 用 `jq`，**不要 inline `python3 -c`**
 
-所有 kb 命令支持 `--agent <name>` 指定操作目标。知识库归属于 workspace，不同 agent 若共享同一 workspace 则访问相同的知识库。
+- **现象**：在 shell 里写 `ctxdb kb list | python3 -c "import json,sys; ..."` 经常因为单/双引号嵌套 escape 失败
+- **根因**：shell + python -c 的引号是两层独立 escape，组合时极容易漏
+- **正确做法**：`ctxdb kb list --agent=qoder | jq '.knowledge_bases[].name'`；jq 表达式在单引号里不需要 escape
 
-不带 `--agent` 时的解析顺序：`CTXDB_AGENT` 环境变量 → `agents.default` 配置段。
+### 注意事项 3：`upload-*` / `create` 是副作用，没明示 KB 名前必须先确认
 
-## Hooks 感知
+- **现象**：用户只说"把这段记进知识库"没指定 KB，agent 直接用了某个猜的 KB 名 → 写到错的桶
+- **根因**：写命令不会跟 agent 二次确认；KB 不存在时报错，但**KB 名拼错却恰好命中另一个真实 KB**时会静默写错
+- **正确做法**：用户没明示 → 必须先 `kb list` 拿候选清单，跟用户确认目标后才执行
 
-**KB 目录注入**：如果对话中出现 `<available-knowledge-bases>` 块，表示 hooks 已启用，该块列出可用知识库名称，可直接用于 `--kb=<name>` 参数。
+### 注意事项 4：`kb search` 空结果时降阈值再试一次
+
+- **现象**：query 明明跟内容相关，但 `chunks: []`
+- **根因**：默认 `--threshold=0.4`，短 query / 关键词偏冷时打不到
+- **正确做法**：降到 `--threshold=0.2` 或 `--threshold=0.3` 重试一次再判定真的没命中；仍空才放弃
+
+### 注意事项 5：`upload-*` 不会自动建 KB
+
+- **现象**：`kb upload-text foo bar --text=...` 报错 "kb 'foo' not found"
+- **根因**：上传命令只写已有 KB，**不会**为了你 implicit 建一个
+- **正确做法**：先 `ctxdb kb create foo --agent=qoder`，再 upload
+
+## 6. 高级参数
+
+### `kb search` 全部 flag
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `--kb=<name1,name2>` | 限定搜索的 KB，逗号分隔 | 搜所有 |
+| `--top-k=N` | chunk 数上限 | 6 |
+| `--threshold=F` | 相关度阈值 | 0.4 |
+| `--verbose` | 每个 chunk 加 `doc_name` / `kb_id` / `doc_id` / `tags` | false |
+| `--raw` | 服务端原始响应（13+ 字段，含 tokenizer 细节） | false |
+
+### `kb upload-file` / `kb upload-text` 全部 flag
+
+| 参数 | 说明 |
+|------|------|
+| `--doc-name` | （`upload-file`）服务端文档名，默认取本地文件名 |
+| `--file-path` | 服务端逻辑路径（归档/分类用） |
+| `--no-wait` | 不等 chunking 完成立即返回 |
+
+### `kb create` 全部 flag
+
+| 参数 | 说明 |
+|------|------|
+| `--description` | 知识库描述 |
+
+### `kb list` / `kb documents-list` / `kb document-get`
+
+无额外 flag（除通用参数）。
+
+### 通用参数
+
+| 参数 | 说明 |
+|------|------|
+| `--agent=<name>` | **必填**。指定操作哪个 agent 的配置桶（`qoder` / `codex` / `claude` / `default`） |
 
-**B-3c 守卫**：包含 `kb upload-text` 或 `kb upload-file` 操作的对话轮次，其内容不会被 autoCapture 写入记忆（防止文档原文混入记忆）。
+`--agent` 解析顺序：
+1. 命令行显式 `--agent=<name>` → 用它
+2. 缺省 → 读 `CTXDB_AGENT` 环境变量
+3. env 也没有 → 落到 `"default"` 桶
+4. 若 `"default"` 桶未通过 `ctxdb setup --api-key=... --base-url=...` 配置过 → exit 2 "config incomplete for agent default"
 
-如果对话中没有 `<available-knowledge-bases>`，表示当前为纯 CLI 模式，用 `kb list` 查看可用知识库。
+## 7. 配置
 
-所有命令输出 JSON 到 stdout，错误输出到 stderr 并返回非零退出码。
+- 配置文件：`~/.ctxdb/ctxdb.json`，分 `agents.<name>` 段（`qoder` / `codex` / `claude` / `default`），互不复用
+- 配置命令：`ctxdb setup --agent <name> --api-key=<key> --base-url=<url> [--user-id=<id>]`
+  - 带 `--agent` 时还会装 hooks + skill；不带 `--agent` 时只写 `agents.default` 段（仅 CLI 用）
+- 连接检查：`ctxdb ping --agent=<name>`
+- 状态查看：`ctxdb status --agent=<name>`

package/dist/setup/skills/contextdb-memory/SKILL.md

@@ -1,142 +1,182 @@
 ---
 name: contextdb-memory
-description: RDS contextdb 记忆操作全量参考。覆盖 memory add / search / list / get / update / delete 的完整参数、JSON 输出结构和 hooks 感知机制。当用户提到"记住"、"记一下"、"查记忆"、"删记忆"、"改记忆"、"之前说过"等场景时使用。
+description: contextdb 长期记忆高频操作（主动记忆 / 搜索过往 / 列出审计 / 改删某条）和命令速查。当用户提到"记住 / 记一下 / 记一笔 / 写进记忆 / 查记忆 / 找记忆 / 列记忆 / 删记忆 / 改记忆 / 之前说过 / 上次提到"等场景时使用。配套 contextdb-knowledge 处理知识库。
 ---
 
-# contextdb Memory 操作参考
+# contextdb Memory 操作
 
-## 配置
+## 1. 什么时候用这个 skill
 
-- 配置文件：`~/.ctxdb/ctxdb.json`
-- 配置命令：`ctxdb setup --api-key=<key> --base-url=<url> [--user-id=<id>]`
-- 带 `--agent <name>` 时写入指定 agent 的配置段并安装 hooks + skill
-- 不带 `--agent` 时写入 `agents.default` 配置段（仅 CLI 使用）
-- 连接检查：`ctxdb ping`，状态查看：`ctxdb status`
+用户在做"写/找/改/删长期记忆"的任何动作时进这个 skill。触发关键词：**记住 / 记一下 / 记一笔 / 写进记忆 / 查记忆 / 找记忆 / 列记忆 / 删记忆 / 改记忆 / 之前说过 / 上次提到**。
 
-## memory add
+- 用户说"记住 X"、"帮我记一下" → §2 recipe 1
+- 用户问"之前我们聊过 Y 吗"、"上次怎么说的" → §2 recipe 2
+- 用户想**审计/排查**记忆是否写进去 → §2 recipe 3
+- 用户要**改某条 / 删某条** → §2 recipe 4
 
-将文本写入长期记忆。
+配套 skill：**contextdb-knowledge**（知识库操作）。两者用同一份 `~/.ctxdb/ctxdb.json` 配置和同一个 `--agent` 路由。
 
-```sh
-ctxdb memory add "<text>" [--no-infer] [--user-id=<id>] [--metadata=K1=V1,K2=V2] [--agent=<name>]
-```
+## 2. 高频 recipes
 
-| 参数 | 说明 |
-|------|------|
-| `<text>` | 要记忆的文本内容（必填） |
-| `--no-infer` | 跳过 LLM fact-extraction，原文直存 |
-| `--user-id` | 覆盖配置中的 user_id |
-| `--metadata` | 附加键值对元数据，逗号分隔 |
-| `--agent` | 指定操作哪个 agent 的记忆桶（默认使用 agents.default 配置） |
-
-服务端默认走同步模式（`async_mode: false`），等待 LLM fact-extraction 完成后返回结果。`--no-infer` 跳过提炼，适用于需要原文保留的场景（如项目代号、精确数值）。
-
-**输出 JSON 结构**（同步模式）：
-
-```json
-{
-  "results": [
-    {
-      "id": "mem-uuid",
-      "memory": "提炼后的事实文本",
-      "event": "ADD"
-    }
-  ]
-}
-```
-
-`event` 可能的值：`ADD`（新增）、`UPDATE`（更新已有记忆）、`NONE`（无新事实提取）。`results` 为空数组表示服务端未从输入中提取出新事实。
+> 命令里 `--agent=qoder` 是必填参数。如果用户跑别的 agent（codex / claude），把 `qoder` 替换成对应名字。
 
-## memory search
+### Recipe 1：主动记忆（"记住 X"）
 
-搜索长期记忆。
+**场景**：用户明确说"记住"、"帮我记一下"、"把这条写进记忆"。
 
 ```sh
-ctxdb memory search "<query>" [--top-k=N] [--threshold=F] [--knowledge] [--verbose] [--raw] [--agent=<name>]
+ctxdb memory add "<text>" --agent=qoder
 ```
 
-| 参数 | 说明 | 默认值 |
-|------|------|--------|
-| `<query>` | 搜索文本（必填） | |
-| `--top-k` | 返回条数上限 | 5 |
-| `--threshold` | 相关度阈值 | 0.4 |
-| `--knowledge` | 同时搜索知识库 chunks | false |
-| `--verbose` | 增加 doc_name/kb_id 等字段（knowledge 模式） | false |
-| `--raw` | 服务端原始响应 | false |
-| `--agent` | 指定操作哪个 agent 的记忆桶 | agents.default |
-
-**输出 JSON 结构**：
-
-```json
-{
-  "results": [
-    {
-      "id": "mem-uuid",
-      "memory": "事实文本",
-      "score": 0.85
-    }
-  ]
-}
-```
+默认走 LLM fact-extraction（同步等结果）。想原文存（项目代号 / 精确数值）加 `--no-infer`（见 §6）。
 
-`results` 为空数组表示未找到匹配记忆。
+**何时不适用**：用户没明示要记 → 不要主动调；autoCapture 已在每轮 Stop hook 自动跑（见 §4）。
 
-带 `--knowledge` 时额外返回 `knowledge` 数组（每项含 `content` / `score`，`--verbose` 增加 `doc_name` / `kb_id` / `doc_id` / `tags`）。
+**`event: NONE` 情况**：返回 `results: []` 时表示 LLM 觉得没新事实可提，是**正常返回不是错误**（见 §5 注意事项 1）。
 
-## memory list
+### Recipe 2：找过去说过的（搜记忆）
 
-列出记忆。
+**场景**：用户问"之前我们讨论过 X 吗"、"上次怎么说的"、"我之前提过 Y 没"。
 
 ```sh
-ctxdb memory list [--page-size=N] [--category=<cat>] [--agent=<name>]
+ctxdb memory search "<query>" --agent=qoder
 ```
 
-| 参数 | 说明 | 默认值 |
-|------|------|--------|
-| `--page-size` | 每页条数 | 100 |
-| `--category` | 按分类过滤 | |
+返回 `results` 数组，每项含 `id` / `memory` / `score`，按 score 倒序。top-5 默认。想同时搜知识库 chunks 加 `--knowledge`（见 §6）。
+
+**何时不适用**：用户想看的是当前会话的原对话（不是提炼后的事实） → 走 transcript / 聊天记录而非这个命令；记忆桶里只有提炼版（见 §5 注意事项 2）。
 
-## memory get
+### Recipe 3：浏览/审计记忆
 
-查看单条记忆。
+**场景**：排查"刚才那条记进去没"、用户想看"系统记了我什么"。
 
 ```sh
-ctxdb memory get <memory-id> [--agent=<name>]
+ctxdb memory list --page-size=20 --agent=qoder
 ```
 
-## memory update
+返回 `results` 数组（含 `total` 计数）。按 category 过滤加 `--category=<cat>`（见 §6）。
 
-修改记忆内容。
+**何时不适用**：明确知道要找某关键词 → 用 recipe 2 更精准。
+
+### Recipe 4：改/删某条记忆
+
+**场景**：用户说"把那条改成 X"、"删掉之前关于 Y 的记忆"。
 
 ```sh
-ctxdb memory update <memory-id> --text="<new-text>" [--agent=<name>]
+# 改
+ctxdb memory update <memory-id> --text="<new-text>" --agent=qoder
+
+# 删单条
+ctxdb memory delete <memory-id> --agent=qoder
 ```
 
-## memory delete
+`<memory-id>` 必须先用 recipe 2 或 recipe 3 拿到。
 
-删除记忆。
+**何时不适用**：用户说"清空所有记忆" → 走 `ctxdb memory delete --all`，**必须先跟用户二次确认**（见 §5 注意事项 3，不可逆操作）。
 
-```sh
-ctxdb memory delete <memory-id> [--agent=<name>]
-ctxdb memory delete --all [--agent=<name>]
-```
+## 3. 命令速查
+
+`--agent=<name>` 必填；详细解析链见 §6。其他 advanced flag 见 §6。
+
+| 子命令 | minimal signature |
+|---|---|
+| `memory add` | `ctxdb memory add "<text>" --agent=<name>` |
+| `memory search` | `ctxdb memory search "<query>" --agent=<name>` |
+| `memory list` | `ctxdb memory list --agent=<name>` |
+| `memory get` | `ctxdb memory get <memory-id> --agent=<name>` |
+| `memory update` | `ctxdb memory update <memory-id> --text="<new-text>" --agent=<name>` |
+| `memory delete` | `ctxdb memory delete <memory-id> --agent=<name>` <br> `ctxdb memory delete --all --agent=<name>` |
+
+所有命令 JSON 写 stdout、错误写 stderr 非零退出码。
+
+## 4. Hooks 感知
+
+**`<recalled-memories>` 块**：UserPromptSubmit hook 在每个 user prompt 提交时自动用 prompt 作 query 跑 `memory search`，把命中的 top-K 记忆塞进 system context。存在 → 当前在 hook 环境（recall 自动）。
+
+**autoCapture（Stop hook）**：每轮对话结束后服务端异步提炼事实写记忆，**不用 agent 主动调** `memory add`。`memory add` 用于用户**明确强调**的内容（强加重要性）。
+
+**B-3c 守卫**：含 `kb upload-text` / `kb upload-file` 的轮次，**autoCapture 跳过**这一轮（防文档原文进记忆桶）。
 
-`--all` 删除当前 user_id 下的所有记忆。
+**纯 CLI 模式**：对话里没 `<recalled-memories>` 块 → 不在 hook 环境（裸 CLI），所有 recall / capture 只能主动 `ctxdb memory search` / `ctxdb memory add`。
 
-## --agent 参数
+## 5. 注意事项
 
-所有 memory 命令支持 `--agent <name>` 指定操作目标。不同 agent 的记忆存储在各自的配置桶中（由 `~/.ctxdb/ctxdb.json` 的 `agents.<name>.user_id` 决定）。
+### 注意事项 1：`memory add` 返回 `event: NONE` 是正常的
 
-不带 `--agent` 时的解析顺序：`CTXDB_AGENT` 环境变量 → `agents.default` 配置段。
+- **现象**：调 `memory add "<text>"` 后 `results` 为空数组、`event: NONE`
+- **根因**：服务端默认走 LLM fact-extraction，LLM 判断这段话**没新事实可提**（已存在 / 太啰嗦 / 不构成事实）
+- **正确做法**：想强制原文存加 `--no-infer`；如果用户输入的就是"已知事实重复"，告诉用户"系统认为这条不构成新事实"而不是判定写失败
 
-## Hooks 感知
+### 注意事项 2：`memory search` 拿到的是**提炼后事实**，不是原对话
 
-**autoCapture**：如果对话中出现 `<recalled-memories>` 块，表示 Stop hook 在每轮对话结束后自动提取事实写入记忆。`memory add` 在此基础上用于用户主动强调的内容（加强记忆）。
+- **现象**：用户问"上次我说过 X 吗"，`memory search "X"` 返回的是 LLM 提炼出的事实，跟用户原话措辞不同；用户会觉得"这不是我说的"
+- **根因**：autoCapture / `memory add` 默认走 fact-extraction，存的是提炼版
+- **正确做法**：要拿用户原话 → 看 transcript / 聊天记录文件；记忆桶只能告诉你"用户曾说过类似 X 这个事实"
 
-**autoRecall**：`<recalled-memories>` 块内容是 UserPromptSubmit hook 自动搜索当前 prompt 相关记忆的结果。
+### 注意事项 3：`memory delete --all` 不可逆，**必须二次确认**
+
+- **现象**：用户说"清空记忆"，agent 直接跑 `memory delete --all`
+- **根因**：这条命令清掉当前 `--agent` 桶下绑定 user_id 的**所有**记忆；服务端不存软删，事后无法恢复
+- **正确做法**：跑之前必须跟用户确认"将清空 agent=<name> 桶下所有记忆，不可恢复，确认吗？"；用户回 yes 才执行
+
+### 注意事项 4：`--user-id` 覆盖配置桶，**别随手传**
+
+- **现象**：调 `memory add "..." --user-id=foo` 后 `memory search` 找不到（搜默认桶）；或反过来 search 用了 `--user-id` add 没用 → 写一个桶搜另一个桶
+- **根因**：`--user-id` 直接覆盖配置文件里 `agents.<name>.user_id`，桶就切了
+- **正确做法**：除非你明确知道"现在要操作另一个 user 的记忆"，**否则不要传 `--user-id`**。让默认配置 user_id 兜底，写读自动一致
+
+## 6. 高级参数
+
+### `memory add` 全部 flag
+
+| 参数 | 说明 |
+|------|------|
+| `--no-infer` | 跳过 LLM fact-extraction，原文直存（项目代号 / 精确数值用）|
+| `--metadata=K1=V1,K2=V2` | 附加键值对元数据，逗号分隔 |
+| `--user-id=<id>` | 覆盖配置 user_id（**慎用**，见 §5 注意事项 4）|
+
+服务端默认同步模式（`async_mode: false`），等 LLM 完成才返回。`event` 字段可能：`ADD` / `UPDATE` / `NONE`。
+
+### `memory search` 全部 flag
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `--top-k=N` | 返回条数上限 | 5 |
+| `--threshold=F` | 相关度阈值 | 0.4 |
+| `--knowledge` | 同时搜知识库 chunks | false |
+| `--verbose` | knowledge 模式下加 `doc_name` / `kb_id` / `doc_id` / `tags` | false |
+| `--raw` | 服务端原始响应 | false |
+| `--user-id=<id>` | 覆盖配置 user_id（**慎用**）| |
+
+带 `--knowledge` 时输出额外 `knowledge` 数组（结构同 contextdb-knowledge 的 `chunks`）。
+
+### `memory list` 全部 flag
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `--page-size=N` | 每页条数 | 100 |
+| `--category=<cat>` | 按分类过滤 | |
+
+### `memory get` / `memory update` / `memory delete`
+
+无额外 flag（除通用参数）。`delete --all` 见 §5 注意事项 3。
+
+### 通用参数
+
+| 参数 | 说明 |
+|------|------|
+| `--agent=<name>` | **必填**。指定操作哪个 agent 的配置桶（`qoder` / `codex` / `claude` / `default`） |
 
-**B-3c 守卫**：包含 `kb upload-text` 或 `kb upload-file` 操作的对话轮次，其内容不会被 autoCapture 写入记忆（防止文档原文混入记忆）。
+`--agent` 解析顺序：
+1. 命令行显式 `--agent=<name>` → 用它
+2. 缺省 → 读 `CTXDB_AGENT` 环境变量
+3. env 也没有 → 落到 `"default"` 桶
+4. 若 `"default"` 桶未通过 `ctxdb setup --api-key=... --base-url=...` 配置过 → exit 2 "config incomplete for agent default"
 
-如果对话中没有 `<recalled-memories>`，表示当前为纯 CLI 模式，所有操作需主动调用。
+## 7. 配置
 
-所有命令输出 JSON 到 stdout，错误输出到 stderr 并返回非零退出码。
+- 配置文件：`~/.ctxdb/ctxdb.json`，分 `agents.<name>` 段（`qoder` / `codex` / `claude` / `default`），互不复用
+- 配置命令：`ctxdb setup --agent <name> --api-key=<key> --base-url=<url> [--user-id=<id>]`
+  - 带 `--agent` 时还会装 hooks + skill；不带 `--agent` 时只写 `agents.default` 段（仅 CLI 用）
+- 连接检查：`ctxdb ping --agent=<name>`
+- 状态查看：`ctxdb status --agent=<name>`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliyunrds/ctxdb",
-  "version": "0.0.7",
+  "version": "0.0.8-beta.1",
   "type": "module",
   "description": "Unified access layer for RDS ContextDatabase: `ctxdb` CLI (memory + KB ops), one-shot `setup --agent <qoder|codex|claude>` installer, per-agent config, hooks, and SKILL.md.",
   "license": "Apache-2.0",
@@ -25,7 +25,7 @@
   ],
   "author": "kuahai",
   "engines": {
-    "node": ">=22"
+    "node": ">=20"
   },
   "dependencies": {
     "@aliyunrds/ctxdb-shared": "~0.0.3"
@@ -39,7 +39,6 @@
   },
   "scripts": {
     "build": "tsup && mkdir -p dist/setup && cp -r src/setup/skills dist/setup/ && chmod +x dist/hooks/*.js dist/cli/main.js",
-    "postinstall": "chmod +x dist/hooks/*.js dist/cli/main.js 2>/dev/null || true",
     "test": "vitest run"
   }
 }