ctxdb0

@polardbx/ctxdb0 是 Context0 面向 Coding Agent 的本地插件。它通过生命周期 Hook 自动沉淀上下文，并通过一个显式 CLI 提供记忆、知识库、会话和托管 Skill 能力。

当前实现是 vNext beta：包名和主命令仍为 @polardbx/ctxdb0 / ctxdb0，旧的 stdio MCP、PostCompact、transcript 游标和 live-sync 实现已移除。为避免升级后直接 command not found，发布包暂时保留 ctxdb CLI 别名和两个只输出迁移指引的 MCP 退役入口；它们不会恢复 MCP Server。

核心行为

• 默认每个有效完成回合调用 POST /v3/memories/add，立即进入后端异步长期记忆提炼。
• 可选 session_batch_enabled=true：逐轮保存 Session 原始消息，并在 SessionEnd 统一触发提炼。该选项默认关闭，且同一会话内策略被冻结，不会双写。
• Prompt Hook 的记忆召回采用 manual | intent | always 策略，默认 intent。
• Prompt Hook 自动查询 KB 默认关闭；开启时必须固化明确的知识源 ID 范围。
• Agent 可按静态 Skill 的指导，通过自然语言要求把已验证内容整理并上传到指定 KB。
• 本包不包含 stdio MCP Server。后端原生 MCP 是完全独立的能力，不由 ctxdb0 安装、代理或配置。
• 本包不保存 transcript 行号、字节位置、消息计数或同步游标；回合幂等依赖事件 ID 与有界投递账本。
• @polardbx/ctxdb0-sync 是独立产品。ctxdb0 不修改它的源码、配置、锁、checkpoint 或 watermark。

支持的 Host

| Host | 安装方式 | 回合捕获 | 备注 | |---|---|---|---| | Codex | 原生 Codex plugin marketplace | 完整 | 安装后需在 /hooks 审阅并信任 Hook | | Claude Code | ~/.claude/settings.json + 静态 Skill | 完整 | 新版优先使用 prompt_id；旧版以本地 capture ID 关联 | | Qoder CLI | ~/.qoder/settings.json + 静态 Skill | 完整 | Host 未提供 turn ID，插件在 prompt 时生成 capture ID | | QoderWork | ~/.qoderwork/settings.json + 静态 Skill | 降级 | 官方 Stop 协议未提供最终 assistant 文本，不声称完成自动回合沉淀 | | Qwen Code | ~/.qwen/settings.json + 静态 Skill | 完整 | Host 未提供 turn ID，插件在 prompt 时生成 capture ID；tool-result 续轮的 UserPromptSubmit 自动跳过 | | Hermes Agent | ~/.hermes/config.yaml + 静态 Skill | 完整 | 使用 session start/finalize 与 LLM pre/post 四类 Hook；首次安装后需显式接受 allowlist |

各 Host 使用独立 Adapter 与协议 fixture，不通过“兼容 Claude”来推断字段。

安装与连接

要求 Node.js 22 或更高版本。

公网 npm 发布后可从 npmjs 安装：

npm install -g @polardbx/ctxdb0 --registry https://registry.npmjs.org

仓库根目录的安装脚本默认走阿里内部 anpm。公网机器必须显式选择 npmjs：

# 内网默认渠道
bash scripts/install.sh --yes

# 公网渠道
bash scripts/install.sh --registry https://registry.npmjs.org --yes

安装后再建立连接：

ctxdb0 --version

printf '%s' "$CTXDB0_API_KEY" | ctxdb0 connect \
  --profile local \
  --endpoint https://context0.example.com \
  --user-id alice \
  --api-key-stdin \
  --json

ctxdb0 attach --host claude --json
ctxdb0 doctor --host claude --json

发布包的命令入口分为两类：

• 正式入口：ctxdb0、ctxdb0-hook。
• 迁移兼容入口：ctxdb 精确转发到 ctxdb0；ctxdb-mcp、ctxdb0-mcp 立即以非零状态退出并提示执行 ctxdb0 migrate --plan --json 和重新 attach。后两者不是 stdio MCP Server，不读 stdin、不实现 JSON-RPC，也不依赖 MCP SDK。

connect 将非敏感配置写入 ~/.ctxdb0/plugin/config.json，凭据单独写入权限为 0600 的 credentials.json。远程 endpoint 必须使用 HTTPS；HTTP 只允许 localhost、127.0.0.1 或 ::1，且 endpoint 不允许 path prefix、凭据、query 或 fragment。

项目级 .ctxdb0.json 是不可信输入，不能选择 profile、user、endpoint 或 project_ref，只能单调收紧全局 profile 已允许的自动行为：降低 recall_mode、关闭 session batch、关闭 Prompt-KB 召回。projectRef 由 canonical 本地项目路径的 SHA-256 摘要自动派生，仅作 provenance，不是授权或租户隔离边界。项目配置中出现 API Key、token、password、credential 或 secret 字段会被拒绝。

建议始终在 connect 时提供 --user-id。没有 subject user 时，Prompt Hook 会跳过自动 memory recall，避免 OWNER 凭据意外扩大召回范围；显式 CLI 操作仍按各命令参数与服务端权限执行。

安装其他 Host：

ctxdb0 attach --host codex --json
ctxdb0 attach --host qoder --json
ctxdb0 attach --host qoderwork --json
ctxdb0 attach --host qwen --json
ctxdb0 attach --host hermes --json

安装器只管理带 ctxdb0 owner marker 的 Hook/静态 Skill/Codex marketplace，并保留第三方配置、后端原生 MCP 与 ctxdb0-sync 状态。它会清理已知旧 ctxdb/ctxdbx Hook 和退役 stdio MCP 名称。写 Host 配置前会备份；失败时执行回滚或 Codex CLI 补偿。

静态 Skill 采用 fail-closed 所有权模型：目标目录若已存在但不属于本安装记录，attach 不覆盖；manifest 记录目录 SHA-256，refresh 遇到漂移会拒绝覆盖，detach 也只删除 owner 与 hash 均匹配的资产。

静态 Skill

包内唯一静态 Skill 为 skills/ctxdb0-context。安装后，Agent 能根据用户自然语言选择相应 CLI，例如：

• “找一下我们上次确定的缓存方案” → ctxdb0 memory recall ...
• “把这份结论沉淀到架构 KB” → 先确认知识源，再用 stdin 调用 ctxdb0 knowledge import
• “恢复昨天的会话” → ctxdb0 sessions browse 后按明确 ID restore
• “安装事故处理 runbook” → ctxdb0 skills search/fetch，并按下载完整性规则校验

静态 Skill 覆盖所有公开命令，并明确写操作授权、知识源范围、删除确认、凭据保护及不可信召回内容的处理规则。

托管 Skill 下载会校验 package/resource SHA-256。资源默认只能从当前 Context0 endpoint 同源下载；OSS 等跨源 HTTPS 地址必须由用户在逗号分隔的 CTXDB0_SKILL_DOWNLOAD_ORIGINS 中显式列出 bare origin（例如 https://skills-oss.example.com）。HTTP 仍只允许 loopback，下载不跟随 redirect。

常用命令

所有命令都支持 --json，Agent 调用应始终使用它。

# 配置与诊断
ctxdb0 doctor --json
ctxdb0 config show --json
ctxdb0 config set recall-mode intent --json
ctxdb0 config set session-batch off --json
ctxdb0 config set prompt-knowledge-recall off --json
ctxdb0 refresh --host claude --json
ctxdb0 detach --host claude --json

# 记忆
printf '%s' '以后发布先做 10% canary' | ctxdb0 memory remember --stdin --json
ctxdb0 memory recall '发布策略' --limit 5 --json
ctxdb0 memory browse --offset 0 --limit 20 --json
ctxdb0 memory show <memory-id> --json
printf '%s' '替换后的内容' | ctxdb0 memory revise <memory-id> --stdin --json
ctxdb0 memory forget <memory-id> --confirm-id <memory-id> --json

# 知识库
ctxdb0 knowledge sources --json
ctxdb0 knowledge sources create --name architecture --description '架构决策' --json
ctxdb0 knowledge query '灰度发布要求' --source architecture --json
ctxdb0 knowledge documents --source architecture --json
ctxdb0 knowledge documents show <document-id> --source architecture --json
printf '%s' '# 决策\n...' | ctxdb0 knowledge import \
  --source architecture --title '灰度发布决策' --stdin --json
ctxdb0 knowledge import --source architecture --file ./docs/adr.md --json

# 会话与托管 Skill
ctxdb0 sessions browse --page 0 --limit 20 --json
ctxdb0 sessions restore <session-id> --json
ctxdb0 skills search 'incident response' --json
ctxdb0 skills fetch <skill-id> --json

知识源创建与文档导入是两个独立写操作。只有用户明确要求新建缺失知识源时，才使用：

printf '%s' '<document>' | ctxdb0 knowledge import \
  --source new-source --title title --stdin --create-source --json

行为配置

默认值：

{
  "startup_budget": 1200,
  "recall_mode": "intent",
  "recall_budget": 600,
  "prompt_knowledge_recall": {
    "enabled": false,
    "source_ids": [],
    "scope_origin": "explicit",
    "scope_captured_at": null,
    "limit": 4
  },
  "session_batch_enabled": false,
  "debug": false
}

开启 Prompt-KB 自动召回必须明确限定范围：

ctxdb0 config set prompt-knowledge-recall on \
  --source architecture --source runbooks --json

# 只有用户明确要求当前所有可访问知识源时才使用；命令会把当时的 ID 快照固化到配置
ctxdb0 config set prompt-knowledge-recall on --all-accessible --json

--source 与 --all-accessible 互斥。空范围、名称歧义、不存在、无权限或超过 100 个知识源都会失败关闭。

Prompt memory recall 与 Prompt-KB recall 是两条独立召回腿：前者还要求连接 profile 配有 subject user_id；没有 subject user 时自动 memory recall 始终跳过。

状态和所有权

ctxdb0 的可写命名空间只有 ~/.ctxdb0/plugin/：

~/.ctxdb0/plugin/
├── config.json
├── credentials.json
├── installations.json
├── assets/
├── managed-skills/
├── state/
│   ├── sessions/
│   ├── turn-envelopes/
│   └── delivery/
├── backups/
├── legacy/
└── logs/ctxdb0.jsonl

状态文件采用散列文件名、有限 TTL 和 0600/0700 权限。投递记录保存事件键、payload hash、状态和安全的服务端引用，不保存 API Key 或 transcript 位置。

以下路径不属于插件，migrate、detach 和 purge 都不得修改：

• ~/.ctxdb0/sync-state.json
• ~/.ctxdb0/locks/
• 项目 .ctxdb0-sync.json
• access_layer/ctxdbx-sync/

迁移与清理

迁移不会自动沿用旧 auto_recall、warmup_recall、recall_knowledge、live_sync 或游标状态。先查看计划和审阅报告，再用同一计划生成的确认 token 应用：

ctxdb0 migrate --plan --json
ctxdb0 migrate --apply --confirm <confirmation-token> --json

旧脚本中的 ctxdb ... 可在兼容期继续执行同一套新 CLI 命令，但新文档和自动化应改用 ctxdb0。若旧 Agent 配置仍启动 ctxdb-mcp 或 ctxdb0-mcp，兼容入口会明确报错而不是伪装成 MCP Server；删除该 MCP 配置项，再运行上面的迁移计划并执行 ctxdb0 attach --host <host> --json。后端原生 MCP 如需启用，应按后端独立文档单独配置，不能把这两个退役入口当作代理。

如果检测到旧 SessionEnd 批处理 Hook，报告会标记 review required 并列出两种策略；迁移目标仍默认逐轮异步，只有用户迁移后显式 config set session-batch on 才会重新开启批处理。

彻底清理前，先逐个 detach --host 移除 Host 资产，再执行：

ctxdb0 purge --plan --json
ctxdb0 purge --confirm <confirmation-token> --json

purge 只删除 ~/.ctxdb0/plugin/，不会删除 ~/.ctxdb0/ 或 ctxdb0-sync 状态。

开发与验证

pnpm install
pnpm typecheck
pnpm lint
pnpm format:check
pnpm test
pnpm test:e2e
pnpm build

测试包含 Host 官方协议 fixture、Adapter、Hook runtime、逐轮/批处理、内容过滤、KB 上传、安装事务、迁移隔离、CLI 路由、网关请求、npm package smoke 和真实二进制 E2E。

更详细的安装和运维说明见 DEPLOY.md，设计依据见 ctxdb0 plugin redesign。