@aliyunrds/ctxdb 0.0.7 → 0.0.8-beta.2

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

@@ -1,142 +1,184 @@
 ---
 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>]
-```
-
-| 参数 | 说明 |
-|------|------|
-| `<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"
-    }
-  ]
-}
-```
+## 2. 高频 recipes
 
-`event` 可能的值：`ADD`（新增）、`UPDATE`（更新已有记忆）、`NONE`（无新事实提取）。`results` 为空数组表示服务端未从输入中提取出新事实。
+> 命令里的 `--agent={{agent}}` 是当前 skill 安装目标。不要把示例改成 `qoder`；如果读到未替换的双花括号 agent 模板，先按 §6 判定真实 agent，再替换成 `qoder` / `qoderwork` / `codex` / `claude` / `default`。
 
-## 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={{agent}}
 ```
 
-| 参数 | 说明 | 默认值 |
-|------|------|--------|
-| `<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={{agent}}
 ```
 
-| 参数 | 说明 | 默认值 |
-|------|------|--------|
-| `--page-size` | 每页条数 | 100 |
-| `--category` | 按分类过滤 | |
+返回 `results` 数组，每项含 `id` / `memory` / `score`，按 score 倒序。top-5 默认。想同时搜知识库 chunks 加 `--knowledge`（见 §6）。
 
-## memory get
+**何时不适用**：用户想看的是当前会话的原对话（不是提炼后的事实） → 走 transcript / 聊天记录而非这个命令；记忆桶里只有提炼版（见 §5 注意事项 2）。
 
-查看单条记忆。
+### Recipe 3：浏览/审计记忆
+
+**场景**：排查"刚才那条记进去没"、用户想看"系统记了我什么"。
 
 ```sh
-ctxdb memory get <memory-id> [--agent=<name>]
+ctxdb memory list --page-size=20 --agent={{agent}}
 ```
 
-## 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={{agent}}
+
+# 删单条
+ctxdb memory delete <memory-id> --agent={{agent}}
 ```
 
-## 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` 用于用户**明确强调**的内容（强加重要性）。
 
-`--all` 删除当前 user_id 下的所有记忆。
+**B-3c 守卫**：含 `kb upload-text` / `kb upload-file` 的轮次，**autoCapture 跳过**这一轮（防文档原文进记忆桶）。
 
-## --agent 参数
+**纯 CLI 模式**：对话里没 `<recalled-memories>` 块 → 不在 hook 环境（裸 CLI），所有 recall / capture 只能主动 `ctxdb memory search` / `ctxdb memory add`。
 
-所有 memory 命令支持 `--agent <name>` 指定操作目标。不同 agent 的记忆存储在各自的配置桶中（由 `~/.ctxdb/ctxdb.json` 的 `agents.<name>.user_id` 决定）。
+## 5. 注意事项
 
-不带 `--agent` 时的解析顺序：`CTXDB_AGENT` 环境变量 → `agents.default` 配置段。
+### 注意事项 1：`memory add` 返回 `event: NONE` 是正常的
 
-## Hooks 感知
+- **现象**：调 `memory add "<text>"` 后 `results` 为空数组、`event: NONE`
+- **根因**：服务端默认走 LLM fact-extraction，LLM 判断这段话**没新事实可提**（已存在 / 太啰嗦 / 不构成事实）
+- **正确做法**：想强制原文存加 `--no-infer`；如果用户输入的就是"已知事实重复"，告诉用户"系统认为这条不构成新事实"而不是判定写失败
 
-**autoCapture**：如果对话中出现 `<recalled-memories>` 块，表示 Stop hook 在每轮对话结束后自动提取事实写入记忆。`memory add` 在此基础上用于用户主动强调的内容（加强记忆）。
+### 注意事项 2：`memory search` 拿到的是**提炼后事实**，不是原对话
 
-**autoRecall**：`<recalled-memories>` 块内容是 UserPromptSubmit hook 自动搜索当前 prompt 相关记忆的结果。
+- **现象**：用户问"上次我说过 X 吗"，`memory search "X"` 返回的是 LLM 提炼出的事实，跟用户原话措辞不同；用户会觉得"这不是我说的"
+- **根因**：autoCapture / `memory add` 默认走 fact-extraction，存的是提炼版
+- **正确做法**：要拿用户原话 → 看 transcript / 聊天记录文件；记忆桶只能告诉你"用户曾说过类似 X 这个事实"
 
-**B-3c 守卫**：包含 `kb upload-text` 或 `kb upload-file` 操作的对话轮次，其内容不会被 autoCapture 写入记忆（防止文档原文混入记忆）。
+### 注意事项 3：`memory delete --all` 不可逆，**必须二次确认**
 
-如果对话中没有 `<recalled-memories>`，表示当前为纯 CLI 模式，所有操作需主动调用。
+- **现象**：用户说"清空记忆"，agent 直接跑 `memory delete --all`
+- **根因**：这条命令清掉当前 `--agent` 桶下绑定 user_id 的**所有**记忆；服务端不存软删，事后无法恢复
+- **正确做法**：跑之前必须跟用户确认"将清空 agent=<name> 桶下所有记忆，不可恢复，确认吗？"；用户回 yes 才执行
 
-所有命令输出 JSON 到 stdout，错误输出到 stderr 并返回非零退出码。
+### 注意事项 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` / `qoderwork` / `codex` / `claude` / `default`） |
+
+`--agent` 解析顺序：
+1. 命令行显式 `--agent=<name>` → 用它
+2. 缺省 → 读 `CTXDB_AGENT` 环境变量
+3. env 也没有 → 落到 `"default"` 桶
+4. 新版本 `ctxdb setup --agent <qoder|qoderwork|codex|claude>` 会在 `agents.default` 缺失时复制当前 agent 配置作为兜底
+5. 若 `"default"` 桶仍不存在或未配置完整 → exit 2 "config incomplete for agent default"
+
+## 7. 配置
+
+- 配置文件：`~/.ctxdb/ctxdb.json`，分 `agents.<name>` 段（`qoder` / `qoderwork` / `codex` / `claude` / `default`），互不复用
+- 配置命令：`ctxdb setup --agent <name> --api-key=<key> --base-url=<url> [--user-id=<id>]`
+  - 带 `--agent` 时还会装 hooks + skill；若 `agents.default` 缺失，会复制当前 agent 配置作为 CLI 兜底
+  - `--agent default` 只写 `agents.default` 段（仅 CLI 用，不装 hooks / skill）
+- 连接检查：`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.2",
   "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"
   }
 }