@yottameta/yotta-memory 0.13.1 → 0.16.0

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: yotta-memory
-description: 元忆 —— 有权限边界的文件式智能体记忆。文件式、零依赖、可 diff/可回滚：让任何 AI 智能体活过会话，开工 recall 恢复上下文、重要信息 remember 落盘、收工归档。类型体系 FACT（公共共享）/ PREF / BOUND / COMMIT（私密隔离）。触发：记住、别忘了、记一笔、记忆、remember、recall、跨会话、上次说到、续测、交接、归档、记忆盘、共享记忆、局域网记忆、画像、开工上下文、记忆守则、profile、context、越用越懂、语义检索、反馈、维护、蒸馏、feedback、maintain、distill、explain、自我学习、自我进化、自我提升、查看平台分页、recall 候选预过滤、任务相关记忆、--focus、--embedding、压缩遗忘、consolidate、周期摘要、自动合并、分类型衰减、回滚、备份、backup、防误删、doctor、事务快照
-version: 0.13.1
+description: 元忆 —— 有权限边界的文件式智能体记忆。文件式、零依赖、可 diff/可回滚：让任何 AI 智能体活过会话，开工 recall 恢复上下文、重要信息 remember 落盘、收工归档。类型体系 FACT（公共共享）/ PREF / BOUND / COMMIT（私密隔离）。触发：记住、别忘了、记一笔、记忆、remember、recall、跨会话、上次说到、续测、交接、归档、记忆盘、共享记忆、局域网记忆、画像、开工上下文、长期理解摘要、近期走廊、会话闭环、记忆守则、profile、context、越用越懂、语义检索、反馈、维护、蒸馏、feedback、maintain、distill、explain、自我学习、自我进化、自我提升、查看平台分页、recall 候选预过滤、任务相关记忆、--focus、--embedding、压缩遗忘、consolidate、周期摘要、自动合并、分类型衰减、回滚、备份、backup、防误删、doctor、事务快照
+version: 0.16.0
 license: MIT
 ---
 
@@ -15,7 +15,11 @@ license: MIT
 - **零依赖**：无 daemon / 无数据库 / 无向量库，Node.js 自带即可运行。
 - **类型体系**：FACT（事实，公共共享）/ PREF（偏好，私密）/ BOUND（边界，私密）/ COMMIT（承诺，私密）。
 - **双级存储**：用户级 `~/.yottamemory/`（跨项目）+ 项目级 `.yottamemory/`（随项目共享）。
-- **越用越懂**：`profile` 聚合用户画像（引擎零推断，只归组原文）+ `context` 一键生成开工上下文包（身份 + 画像 + 近期记忆 + 边界 + 承诺）+ SKILL「记忆守则」规则层；只注入规则与机制，不注入人格数据（出厂零数据）。
+- **越用越懂（v0.14.0）**：`context` 一键生成开工上下文包——长期理解摘要优先（复用 `consolidate` 产物）+ 用户画像（引擎零推断，只归组原文）+ 近期走廊（按更新时间取样）+ 近期高价值补位 + 边界 + 承诺 + 会话闭环契约；SKILL「记忆守则」规则层只注入规则与机制，不注入人格数据（出厂零数据）。
+- **MCP 工具分组（v0.15.0）**：`serve --tools core|full` 控制工具暴露面。`core` 固定为 `context / recall / search / remember`，适合常驻；`full` 为现有 16 工具，适合维护与诊断。未指定时默认 `full`，保持现有配置兼容。
+- **身份模型（v0.16.0）**：身份不再从环境变量读取。HTTP / 远程 MCP 只认请求头 `Authorization` + `X-Agent-Id` + `X-Agent-Key`；stdio MCP 只认显式参数 `--agent-id` + `--agent-key-file`；CLI 用 `--agent` + `--agent-key` / `--agent-key-file`。旧身份 env 会在 MCP 启动时被明确拒绝。
+- **运行时稳定入口（v0.16.0 M2）**：`runtime install --from-current` 把当前引擎安装到 `<runtimeRoot>/versions/<version>/` 并创建 `<runtimeRoot>/current` 稳定指针；`runtime use <version>` 原子切换、`runtime rollback` 回滚、`runtime status` 查看漂移。stdio MCP、`lan enable` 与备份调度只指向 `<runtimeRoot>/current/bin/yotta-memory.js`，不写版本目录。
+- **运行时诊断与握手（v0.16.0 M3）**：`doctor --runtime` 检查 CLI / current / runtime.json / MCP 配置 / 运行中 server / 技能副本 / 身份模式漂移，逐项给出实际版本、期望版本、修复命令和是否阻断；MCP `initialize` / `server/discover` 的 `serverInfo` 返回 `runtimePath` / `identityMode` / `toolProfile`。
 - **自我学习 / 自我进化 / 自我提升（v0.8.0）**：`recall` 语义检索（同义词 / 拼音 / 字段加权 / 模糊匹配，零依赖）；`feedback` 显式使用反馈闭环（useful / useless → weight / confidence / feedback_net 演化，越用越懂）；`maintain` 规则层自组织（统一效用分 + 年龄自动归档 / 遗忘候选 / 去重，默认 dry-run，immutable / BOUND 豁免）；`distill` 心理日志蒸馏（统计摘要 / 主题画像 / 知识地图，可选 `--model` 外部模型增强）；`explain` 查看单条记忆效用分项。
 - **召回质量与上下文选择（v0.9.0）**：`recall` 支持可选本地 embedding 插件（`--embedding <command>` / `config set embedding_cmd <command>`）；`context --focus <关键词>` 生成任务感知上下文；`--explain` 输出选择 trace，无插件时自动降级为词法检索。
 - **压缩遗忘（v0.10.0）**：记忆库长期可用不膨胀——`consolidate` 周期摘要压缩（把超龄 + 低效用 + 长期闲置的同主题旧记忆归纳成**带溯源**的摘要，原文整体进 `.archive/`，`--undo` 一键回滚）；`maintain --dedup` 近重复**自动合并**（置信度分档，`--apply` 批量执行高置信组）；效用分时效改为**分类型衰减**（FACT 慢 / PREF 中 / COMMIT 任务类快 / BOUND 不衰减）；`consolidate --batches` 批次审计可查。
@@ -39,11 +43,19 @@ AI 更新流程：先运行 `yotta-memory --version` 记录当前引擎版本；
 
 ## 核心流程
 
-1. **开工定向**：先按「开工第一步：确认记忆位置 + 智能体身份」检测记忆库与身份，再运行 `yotta-memory context`（主注入：身份 + 用户画像 + 近期记忆 + 边界 + 承诺）恢复上下文，需要细节再 `yotta-memory recall <关键词>`；若有明确任务关键词，用 `context --focus <关键词>` 获得任务相关记忆；项目级记忆优先，其次用户级。
-2. **进行中落盘**：重要信息立即 `yotta-memory remember <type> <subject> <statement>`，不攒到收工。
-3. **收工归档**：写会话小结（COMMIT / 笔记）；旧记录定期 `yotta-memory maintain --apply`（单条低效用归档）+ 记忆多了周期 `yotta-memory consolidate --apply`（同主题压缩成带溯源摘要，`--undo` 可回滚）。
+1. **开工定向**：先按「开工第一步：确认记忆位置 + 智能体身份」检测记忆库与身份，再运行 `yotta-memory context`（主注入：身份 + 长期理解摘要 + 用户画像 + 近期走廊 + 近期高价值 + 边界 + 承诺 + 会话闭环契约）恢复上下文，需要细节再 `yotta-memory recall <关键词>`；若有明确任务关键词，用 `context --focus <关键词>` 获得任务相关记忆；项目级记忆优先，其次用户级。
+2. **进行中落盘**：出现事实 / 偏好 / 边界 / 纠正 / 承诺信号时立即 `yotta-memory remember <type> <subject> <statement> --verify`，不攒到收工。
+3. **收工归档**：收工前复盘本轮，检查是否留下 COMMIT / 会话小结；有关键结论但未落盘时补写并 `recall` 回读，无长期价值不硬凑。旧记录定期 `yotta-memory maintain --apply`（单条低效用归档）+ 记忆多了周期 `yotta-memory consolidate --apply`（同主题压缩成带溯源摘要，`--undo` 可回滚）。
 4. **多智能体纪律**：FACT 写入公共区，PREF / BOUND / COMMIT 只写本智能体私密区；不读取其他智能体私密区。**一切读写一律走 `yotta-memory` CLI / MCP 工具**——禁止用 shell（`Get-ChildItem` / `Get-Content` / `cat` / `ls` / `type` 等）直接读或改记忆库目录下的 `.md` / `index.json` / `tokens.json` / `agents.json` / `grants.json` 等文件，否则会绕过权限边界、读到别的智能体私密内容。
 
+## 会话闭环契约（v0.14.0，AI 必做）
+
+`context` 输出末尾会固定注入这段契约；执行时按三步走：
+
+1. **开工已加载**：身份、长期摘要、画像、近期走廊、边界与承诺以 `context` 输出为准；需要细节再用 `recall` 下钻，不凭印象补全。
+2. **进行中立即写**：出现事实 / 偏好 / 边界 / 纠正 / 承诺信号时，立即 `remember <type> <subject> <statement> --verify`；不攒到收工，不把一次性闲聊当记忆。
+3. **收工前复盘**：复盘本轮是否留下 COMMIT / 会话小结；有关键结论但未落盘时补写并 `recall` 回读；没有长期价值就不硬凑。
+
 ## 可靠性基线（v0.12.0 / v0.12.2）
 
 **目的**：防止初始化覆盖、删除不可逆、备份缺失再次造成记忆库丢失。
@@ -104,8 +116,8 @@ yotta-memory backup doctor --id <备份ID>
 yotta-memory backup restore <备份ID> --to <新目录>
 
 # 恢复演练：恢复到隔离副本，校验 manifest、索引并解密一条测试私密
-# 默认用本机已有的 owner 授权缓存；完全裸恢复请加 --recovery-key
-yotta-memory backup drill [<备份ID>]
+# 解密必须有 --recovery-key 或 --password；legacy keys/cache 不参与
+yotta-memory backup drill [<备份ID>] --recovery-key <钥匙>
 ```
 
 - 备份覆盖：`facts/`、`private/`、`keys/`（排除 `keys/cache/` 授权缓存）、`agents.json`、`index.json`、`.archive/`。
@@ -178,7 +190,7 @@ yotta-memory doctor --json
 
 1. 开工：whoami → iam（身份）→ `context`（主注入）→ `recall`（关键词补细节）。
 2. 进行中：增量写，触发信号即记；`remember --verify` 写后回读确认落盘。
-3. 收工：留交接锚点（COMMIT / 笔记），定期 `archive`。
+3. 收工：先复盘本轮并检查关键结论是否落盘，再留交接锚点（COMMIT / 笔记）；定期 `archive`。
 
 ### 6. 写后验证
 
@@ -218,7 +230,7 @@ yotta-memory doctor --json
    - 输出 `memory_home: <目录>`（已显式设置）→ 直接用该位置。
    - 输出 `memory_home: (未设置，默认 ~/.yottamemory)` → 🔒 征得同意后引导设置：问用户用默认还是指定目录（项目级 `<repo>/.yottamemory`、记忆盘等），确认后 AI 执行 `yotta-memory config set memory_home <目录>`，回读 `config get` 验证。
 2. **已有记忆**：目标目录已存在 `facts/` 等子目录或 `index.json` → 直接 recall；全新目录 → 按「便携记忆盘模式 §0.3」初始化。
-3. **私密区已加密（存在 `keys/`）**：先 `yotta-memory key list` 确认本智能体是否有授权缓存；没有 → 提醒用户 `yotta-memory view` → 在平台「授权本智能体」后再读写私密（公共 FACT 不受影响）。
+3. **私密区已加密（存在 `keys/`）**：先 `yotta-memory key list` 确认本智能体是否有 agent binding；没有 → 告知用户由用户自己执行 `yotta-memory view` → 浏览器打开平台 → 输入主口令 → 点「授权」并保存只展示一次的 `agent_key`。用户授权后服务端会写 `keys/pending/<id>.key`；AI 在新会话执行 `yotta-memory key status <id>`（需要时显式加 `--to <AI_HOME>` 或 `--agent-key-file <文件>`；默认发现规则见下），有 pending 就执行 `yotta-memory key claim <id>`，落到 `<AI_HOME>/.yotta-memory-agent-key` 后再使用 `--agent-key-file`。**升级后首次调用元忆 / 重启会话时**，若输出 `[YTM_MIGRATION_REQUIRED]`，必须主动把 marker、受影响 agent 和处理步骤转达给用户。**AI 不得代替用户执行 `migrate` / `key bind` 迁移**，只负责提醒和讲解（marker 只列仍有私密数据、未绑定的 agent；仅有 legacy cache、无迁移数据的 owner 会单独提示，不进入迁移清单；公共 FACT 不受影响）。
 
 **B. 确认本智能体唯一身份（强制，写私密记忆前必做）**：
 
@@ -231,7 +243,7 @@ yotta-memory doctor --json
    - 回读：`yotta-memory whoami` 显示「已登记 + 自我档案」。
 3. **自我档案校验**：`yotta-memory recall "自我接入档案"`（本智能体）能读回字段才算就绪：
    `agent_id / host / memory_home / mcp_mode（stdio|http）/ engine_url（仅远端）/ token（仅远端；本机不存 token）`，可扩展 `agent_name / user_name / relationship`（`iam --name/--user/--relationship` 写入）。
-4. **本机多智能体**：本机多个 AI 智能体共用引擎时，**每个都必须**在它自己的 MCP 配置里声明唯一 `YOTTA_AGENT_ID`（如 `env: { YOTTA_AGENT_ID: "<该智能体唯一ID>" }`），各自 `whoami` 各回各的、互不撞；本机走 stdio 免 token。
+4. **本机多智能体（v0.16.0 安全模型）**：owner ID 不是身份认证。每个 AI 必须同时持有自己的 `agent_key`。stdio MCP 用显式参数 `--agent-id <id> --agent-key-file <宿主key文件>`；HTTP MCP 用请求头 `X-Agent-Id` + `X-Agent-Key`；CLI 直连用 `--agent <id> --agent-key-file <文件>`。没有 agent_key 时，私密读写一律 fail-closed；身份不再读取 `YOTTA_AGENT_ID` / `YOTTA_MEMORY_AGENT_KEY` / `YOTTA_MEMORY_TRUST_ENV_AGENT`，旧配置启动即拒绝。
 
 **C. 身份红线（强制）**：
 
@@ -240,7 +252,7 @@ yotta-memory doctor --json
 
 **D. 开工主注入（context）**：
 
-- 身份就绪后运行 `yotta-memory context [--limit 10] [--budget 1800]`（远端经 MCP 用 `recall` 补细节）：一键拿到「身份 + 多智能体铁律 + 用户画像摘要 + 近期记忆 + 边界提醒 + 承诺 / 锚点」；`--budget` 控制近期记忆字符预算（token 恒定，不随记忆膨胀）。
+- 身份就绪后运行 `yotta-memory context [--limit 10] [--budget 1800]`（远端经 MCP 用 `recall` 补细节）：一键拿到「身份 + 多智能体铁律 + 用户画像摘要 + 长期理解摘要 + 近期走廊 + 近期高价值记忆 + 边界提醒 + 承诺 / 锚点 + 会话闭环契约」；`--budget` 控制动态记忆字符预算，长期摘要 / 身份 / 铁律 / 画像 / 边界 / 承诺与闭环契约必保（token 恒定，不随记忆膨胀）。
 - 无画像时 context 自动生成一次或降级输出其余段，不报错。
 - 需要深挖旧事再 `recall <关键词>`。
 - 私密记忆（PREF / BOUND / COMMIT）**必须有 owner**：未声明身份写私密会被引擎拒绝（公共 FACT 不受影响）。
@@ -253,26 +265,27 @@ yotta-memory doctor --json
 | 命令 | 作用 |
 |---|---|
 | `yotta-memory init [--project] [--dir <目录>] [--attach] [--encrypt|--no-encrypt]` | 初始化（**新建默认加密**：设主口令 + 抄下恢复钥匙；已有库必须用 `--attach`，默认拒绝覆盖；`--no-encrypt` 降级明文；老明文库用 `migrate`）|
-| `yotta-memory migrate` | 明文私密区 → 密文迁移（需主口令；迁移后打印恢复钥匙；当前智能体自动获得授权缓存）|
+| `yotta-memory migrate` | 明文私密区 → 密文迁移（**由用户执行**；需主口令；迁移后打印恢复钥匙；不写明文授权缓存，授权由用户在 `view` 平台完成）|
 | `yotta-memory view [--port 8788] [--host 127.0.0.1]` | 用户查看平台（本机 Web：口令解锁浏览 / 搜索 / 导出全部 AI 记忆 + 授权 / 吊销 AI + 重设口令 + 显示恢复钥匙）|
 | `yotta-memory reset-password [--password <当前> | --recovery-key <钥匙>] [--new-password <新>]` | 重设主口令（忘口令用恢复钥匙）|
-| `yotta-memory key list / authorize <id> / revoke <id>` | 管理 AI 私密读取授权缓存（authorize 需主口令；revoke 立即吊销该 AI 解密能力）|
+| `yotta-memory key list / bind <id> / rotate <id> / claim <id> [--to <AI_HOME> | --agent-key-file <文件>] / status <id> [--to <AI_HOME> | --agent-key-file <文件>] / revoke <id>` | 管理 agent_key binding（**bind/rotate 由用户执行**，需主口令或恢复钥匙；claim/status 由 AI 读取 pending 并落到宿主目录，按同一 AI_HOME 发现规则；revoke 立即吊销该 AI 解密能力，旧 key 随即校验失败；`key list` 输出 `[YTM_MIGRATION_REQUIRED]` 时提醒用户走 `view` 重新授权）|
 | `yotta-memory remember <type> <subject> <statement> [--owner <id>] [--source <来源>] [--weight <0..>] [--verify] [--no-hint]` | 写入（同 subject+statement 自动更新；--owner 标注归属；--source 记录来源；--weight 重要性权重默认 1.0、去重取 max；--verify 写后回读校验；--no-hint 关闭类型启发式提示）|
 | `yotta-memory recall [关键词] [--type T] [--limit N] [--agent <id>] [--owner <id>] [--all] [--unsafe] [--explain] [--semantic] [--embedding <command>] [--embedding-timeout N]` | 检索（v0.8.0 默认语义检索：同义词 / 拼音全拼+首字母 / 字段加权 / 模糊匹配 + 效用分融合排序；v0.9.0 支持可选本地 embedding 插件，失败自动降级；`--explain` 显示命中理由与效用分项；`--semantic` 显式开启；读取分区过滤；越界读其它智能体私密默认拒绝，需 grant / identity=user / `--unsafe`；`--agent <其它>` 只作身份声明/展示，不授予跨读——读他人私密同样要授权；项目级优先）|
 | `yotta-memory profile [--owner <id>]` | 生成用户画像（聚合 `private/<owner>/` 原文，零推断，写 `profile.md`；跨 owner 默认拒绝）|
-| `yotta-memory context [--limit N] [--owner <id>] [--budget N] [--focus <关键词>] [--explain] [--embedding <command>]` | 生成开工上下文包（身份 + 多智能体铁律 + 画像 + 任务相关记忆 + 近期记忆 + 边界 + 承诺；--budget 字符预算，0=不限；--explain 输出 included / dropped 选择 trace）|
+| `yotta-memory context [--limit N] [--owner <id>] [--budget N] [--focus <关键词>] [--explain] [--embedding <command>]` | 生成开工上下文包（身份 + 多智能体铁律 + 画像 + 长期摘要 + 任务相关记忆 + 近期走廊 + 近期高价值 + 边界 + 承诺 + 会话闭环契约；--budget 控制动态记忆字符预算，0=不限；--explain 输出 included / dropped 选择 trace）|
 | `yotta-memory forget <文件>` | 移入 `.trash/<时间>/` 回收区并写审计（v0.12.0；不再物理删除）|
 | `yotta-memory backup volumes / setup --dir <目录> / status / ensure-daily / schedule enable|disable|status` | 每日自动备份（v0.12.0；只展示实际枚举的异卷、用户确认一次位置后默认每日执行，Windows Task Scheduler / systemd timer / launchd 调度，`serve` 补跑）|
 | `yotta-memory backup create / list / doctor / restore <ID> --to <目录> / drill [<ID>]` | 备份、恢复与恢复演练（v0.12.0；独立盘校验、SHA-256 清单、排除 `keys/cache`、恢复默认只写新目录；drill 验证 manifest / 索引 / 测试私密解密）|
-| `yotta-memory doctor [--json]` | 开工可靠性检查（v0.12.2；根目录 / 密钥库 / 索引 / 身份 / 最近备份；严重异常时锁定破坏性写入）|
+| `yotta-memory doctor [--json] [--runtime] [--mcp-config <文件>] [--skill-dir <目录>]` | 开工可靠性检查（v0.12.2；根目录 / 密钥库 / 索引 / 身份 / 最近备份；严重异常时锁定破坏性写入）；加 `--runtime` 检查 CLI / current / MCP 配置 / 运行中 server / 技能副本漂移 |
 | `yotta-memory archive [--days 180] [--threshold 0.35]` | 归档旧记忆（v0.8.0 统一效用分 + v0.10.0 分类型衰减；immutable / BOUND 豁免；私密归档入 `.archive/private/<owner>/<type>/`；阈值默认读 config `maintain_archived_utility`）|
 | `yotta-memory reindex` | 重建索引（手动改 .md 后校正）|
 | `yotta-memory export [--out f.json]` / `import <f.json>` | 导出 / 导入 |
 | `yotta-memory config set memory_home <目录>` / `config set backup_dir <目录>` / `config get` | 持久记住 / 查看记忆库位置与备份目录（`~/.yottamemory/config.json`）|
-| `yotta-memory whoami` | 查看当前智能体身份与登记状态（读 `YOTTA_AGENT_ID` / `X-Agent-Id`，不猜不默认）|
+| `yotta-memory whoami --agent <id> [--agent-key <key>]` | 查看当前显式身份与登记状态；身份不从环境变量读取 |
 | `yotta-memory iam <id> [--name <显示名>] [--user <用户名>] [--relationship <关系>] [--force]` | 登记本智能体唯一身份并自动落自我档案（`agents.json`，ID 必须唯一；可选扩展显示名 / 用户 / 关系）|
 | `yotta-memory token new --agent <id> [--force]` / `token list` / `token revoke --agent <id>` | 每智能体访问 token：生成 / 列出 / 吊销（登记 `<记忆库>/.server/tokens.json`；同 ID 已被其它来源占用需 `--force` 覆盖，防不同智能体合流）|
-| `yotta-memory serve [--host 0.0.0.0] [--port 8787] [--no-auth] [--stdio]` | 启动 MCP 记忆引擎（streamable HTTP 局域网 / --stdio 本地零进程模式；Bearer token + X-Agent-Id 鉴权）|
+| `yotta-memory serve [--host 0.0.0.0] [--port 8787] [--no-auth] [--stdio] [--tools core|full]` | 启动 MCP 记忆引擎（streamable HTTP 局域网 / --stdio 本地零进程模式；Bearer token + X-Agent-Id + X-Agent-Key 鉴权；工具分组默认 full）|
+| `yotta-memory runtime list / install <tarball|版本> [--from-current] [--force] / use <版本> [--restart] / rollback [--restart] / status` | 运行时稳定入口（runtime.json + versions + current；安装 / 切换 / 回滚 / 查看漂移；`--restart` 尝试重启受管 server，失败自动切回旧版本）；漂移诊断用 `doctor --runtime` |
 | `yotta-memory lan enable [--onstart] / disable / status` | 开机自启管理（Windows：计划任务，默认 ONLOGON、--onstart 开机即启需管理员，非管理员自动降级用户级 Startup 静默自启，v0.6.3 起 VBS 自愈不弹 80070002；Linux：systemd 用户单元，不可用时自动降级用户 crontab @reboot）|
 | `yotta-memory feedback <文件|主题> --useful|--useless [--reason <原因>] [--undo]` | 显式使用反馈（v0.8.0 自我学习闭环：useful → weight×1.2 / useless → weight×0.8，confidence / feedback_net 同步演化；`--undo` 回滚最近一次；审计写 `.archive/feedback-<日期>.jsonl`）|
 | `yotta-memory maintain [--dry-run] [--apply] [--purge] [--threshold N] [--age N] [--dedup] [--dedup --apply] [--merge A,B]` | 记忆自组织（v0.8.0 自我进化 + v0.10.0 自动合并）：默认 dry-run 预览；`--apply` 执行归档（immutable / BOUND 豁免；私密归档入 `.archive/private/<owner>/<type>/`），`--purge` 才真删遗忘候选；`--dedup` 查重并给**置信度分档**（≥0.85 高置信 / 0.65–0.85 建议手动 / 其余忽略），`--dedup --apply` 自动合并同归属高置信组（写批次审计可回滚；与归档互斥，不误归档）；`--merge A,B` 手动合并两条；审计写 `.archive/audit-<日期>.jsonl`）|
@@ -292,7 +305,7 @@ yotta-memory doctor --json
 ├── private/<owner>/index.enc # 加密库：每 owner 加密索引（YTMIDX1，Owner Key 加密）
 ├── .archive/                 # 归档区
 ├── index.json                # 公共 FACT 检索索引（加密库只含公共条目）
-├── keys/                     # 加密库密钥库：salt / <owner>.key.enc(UMK 包裹) / <owner>.key.recovery(恢复钥匙包裹) / recovery.key.enc / cache/<id>.key(授权缓存 600)
+├── keys/                     # 加密库密钥库：salt / <owner>.key.enc(UMK 包裹) / <owner>.key.recovery(恢复钥匙包裹) / recovery.key.enc / bindings/<id>.key.agent；legacy cache/<id>.key 不再加载
 └── agents.json               # 智能体身份登记表（唯一性）
 ```
 
@@ -318,10 +331,73 @@ yotta-memory doctor --json
 
 ### 流程
 1. **建加密库**：`yotta-memory init --encrypt`（新建默认加密）→ 设主口令 → 抄下恢复钥匙离线保存。
-2. **老库迁移**：`yotta-memory migrate`（需主口令）→ 明文私密逐文件加密后删除明文 → 打印恢复钥匙 → 当前智能体自动获得授权缓存，其余 AI 需平台授权。
-3. **AI 读写自己的私密**：AI 声明身份后需**平台授权一次**——`yotta-memory view` → 输口令 → 点「授权 <该AI>」→ 平台把 owner key 写入 `keys/cache/<id>.key`（600 权限）。之后该 AI 正常 `remember / recall / profile / context`（私有读写自动加解密）；未授权时写私密报「需在用户平台授权」，公共 FACT 不受影响。
+2. **老库迁移**：由用户执行 `yotta-memory migrate`（需主口令）→ 明文私密逐文件加密后删除明文 → 打印恢复钥匙。迁移不写明文授权缓存；每个 AI 的重新授权由用户自己在 `yotta-memory view` 平台完成并自行备份弹窗 `agent_key`；AI 随后用 `key status` / `key claim` 领取（AI 只提醒授权，不代执行 `migrate` / `key bind`）。
+3. **AI 读写自己的私密（v0.16.0）**：用户侧完成一次 `yotta-memory view` 授权（或用户自行执行 `yotta-memory key bind <id>`），生成只展示一次的 `agent_key`，并写入 `keys/bindings/<id>.key.agent` 与临时 `keys/pending/<id>.key`。AI 新会话用 `key status` / `key claim` 将 pending 落到 `<AI_HOME>/.yotta-memory-agent-key`，之后 CLI 用 `--agent <id> --agent-key-file <宿主key文件>`；stdio MCP 用 `--agent-id <id> --agent-key-file <宿主key文件>`；HTTP MCP 用 `X-Agent-Id` + `X-Agent-Key` 请求头。owner ID 单独存在时不能解密私密；legacy `keys/cache/<id>.key` 不再加载。
 4. **用户查看全部 AI 记忆**：`yotta-memory view` → 输口令 → 浏览 / 搜索 / 导出全部（含各 AI 私密明文，仅用户可见）。口令只在本地内存派生，不落盘、不发远端；默认仅 127.0.0.1，远程需 `--host` 显式开启。
-5. **口令管理**：`yotta-memory reset-password`（当前口令或恢复钥匙）；`key revoke <id>` 立即吊销某 AI 的授权缓存（该 AI 随即失去解密能力）。
+5. **口令管理**：`yotta-memory reset-password`（当前口令或恢复钥匙）；`key revoke <id>` 立即吊销某 AI 的 agent binding（该 AI 随即失去解密能力）。`view` 平台的「授权」只对未绑定 agent 生成新 key；已绑定的 agent 需先「吊销」再授权，避免误打断在用的 agent_key。
+
+## agent_key 本地领取与恢复流程（v0.14.0，AI 必读）
+
+> 目标：用户只负责在 `view` 平台授权和备份弹窗 key；AI 负责把待领取 key 落到自己的宿主目录，并在新会话稳定读取。模型上下文不需要出现 key 明文。
+
+### 1. 首次授权
+
+1. 用户在 `yotta-memory view` 中解锁并点「授权」。
+2. 引擎生成该 AI 的 `agent_key`，写入：
+   - 校验器：`keys/bindings/<agent_id>.key.agent`
+   - 临时待领取：`keys/pending/<agent_id>.key`
+3. 页面弹窗显示一次 `agent_key`。**这是用户侧备份**，用户可选择保存到密码管理器或自己保管；AI 不要求用户把 key 发到聊天。
+
+### 2. AI 新会话领取
+
+AI 在开工身份检查后执行：
+
+```bash
+yotta-memory key status <agent_id>
+```
+
+若输出 `pending: yes`，执行：
+
+```bash
+yotta-memory key claim <agent_id>
+```
+
+`AI_HOME` 解析优先级由 `claim` / `status` 共用：
+
+1. 显式 `--to <目录>` 或 `--agent-key-file <文件>`；
+2. `YOTTA_MEMORY_AGENT_HOME` 或 `YOTTA_MEMORY_AGENT_KEY_FILE`；
+3. 宿主默认：Codex 使用 `$CODEX_HOME`（未设置时 `~/.codex`）、OpenCode 使用 `$XDG_CONFIG_HOME/opencode`、其他宿主使用 `~/.<agent_id>`；
+4. 文件名统一为 `.yotta-memory-agent-key`。
+
+`key status` 即使目标文件不存在也会输出 `checked: <实际检查路径>` 与 `discovery: <命中的发现规则>`，不要仅凭 `host_key: missing` 重复 `claim`。
+
+`claim` 会：
+
+1. 读取 `keys/pending/<agent_id>.key`
+2. 用 binding 验证 key 是否正确
+3. 原子写入 `<AI_HOME>/.yotta-memory-agent-key`
+4. 回读校验
+5. 删除 pending 文件
+
+成功后 CLI 使用：
+
+```bash
+yotta-memory context --agent <agent_id> --agent-key-file <AI_HOME>/.yotta-memory-agent-key
+```
+
+MCP 模式由宿主显式声明身份：stdio 用 `--agent-id <agent_id> --agent-key-file <AI_HOME>/.yotta-memory-agent-key`；HTTP 用 `X-Agent-Id` + `X-Agent-Key` 请求头。宿主不得再用身份环境变量。
+
+### 3. key 丢失与重新授权
+
+- AI 宿主 key 文件丢失、用户还留着弹窗备份：把备份写回 `<AI_HOME>/.yotta-memory-agent-key`，不需要重新授权。
+- AI 文件和用户备份都丢失：用户先在 `view` 中「吊销」，再「授权」。新 key 会重新生成；**旧 key 立即校验失败**，pending 会重新产生，AI 再执行一次 `key claim`。
+- `key revoke` 会删除 binding 和 pending；长驻 MCP 进程也会在后续读取时重新校验 binding，不能继续使用旧 key。
+
+### 4. 安全边界
+
+- pending 文件与宿主 key 文件是临时/本地凭据，备份和 export 默认排除 pending。
+- 本模型不承诺对抗同一 OS 用户下的恶意进程；其他 AI 若拥有同用户文件读取能力，理论上仍可能读取宿主 key。
+- 用户弹窗备份用于恢复，AI 宿主 key 用于运行；两者职责分离。
 
 ## 便携记忆盘模式（局域网多机共享）
 
@@ -356,7 +432,7 @@ yotta-memory doctor --json
 > 记忆盘场景：硬盘插上 → AI 检查盘上目录是否有数据 → 有则接入 + config 记住 → 插盘即恢复，机器记住位置。
 
 **步骤 0.5 启动记忆引擎（仅引擎主机，供远程接入）**
-- 本机若作引擎：🔒 **征得同意后**启动服务——临时运行 `yotta-memory serve`（默认 `0.0.0.0:8787`，Bearer token + X-Agent-Id 鉴权；`--no-auth` 仅限可信内网），或注册开机自启 `yotta-memory lan enable`（Windows：优先计划任务，默认登录自启；非管理员自动降级用户级 Startup 静默自启，免管理员）。
+- 本机若作引擎：🔒 **征得同意后**启动服务——临时运行 `yotta-memory serve`（默认 `0.0.0.0:8787`，Bearer token + X-Agent-Id + X-Agent-Key 鉴权；`--no-auth` 仅限可信内网），或注册开机自启 `yotta-memory lan enable`（Windows：优先计划任务，默认登录自启；非管理员自动降级用户级 Startup 静默自启，免管理员）。
 - 本地零进程模式：本机 AI 也可用 `serve --stdio` 由 MCP 客户端按需拉起 CLI（无常驻进程）。
 - 远程客户端接入前，先确认引擎主机 serve 已运行（`lan status` 可查）。
 
@@ -376,14 +452,15 @@ yotta-memory doctor --json
 ### 4.4 本机直连
 确认记忆库目录（`config get` / `YOTTA_MEMORY_HOME` / 默认 `~/.yottamemory`）→ 直接 CLI 读写，**不配置 MCP、不需要 token**。
 
-### 4.5 远程连接：AI 引导用户获取 token（用户只做复制粘贴）
+### 4.5 远程连接：AI 引导用户获取 token 与 agent_key
 1. AI 告知需要为本智能体申请访问 token。
 2. AI 引导用户在**引擎主机**执行：`yotta-memory token new --agent <本智能体ID>`（引擎主机没装 → 按 4.0 先装；或请引擎主机上的 AI 代执行）。
 3. 命令打印 token（`ytm_...`），只打印一次，请用户妥善保管。
-4. AI 请用户复制 token 发给 AI。
-5. 用户发来 → AI 继续 4.6。
+4. 确认本智能体已持有 `agent_key`；没有时由用户在引擎主机执行 `yotta-memory view` 授权并保存弹窗 key，引擎会同时写 `keys/pending/<id>.key`。
+5. 如果 AI 宿主与记忆库同机或能访问同一文件系统：AI 执行 `yotta-memory key status <id>`，有 pending 就 `key claim`，写到 `<AI_HOME>/.yotta-memory-agent-key`（需要时显式加 `--to` / `--agent-key-file`）。
+6. 如果 AI 宿主与引擎主机不共享文件系统：pending 不能跨机自动读取。用户必须通过密码管理器、加密文件传输或目标主机本地输入把 key 放到 AI 宿主目录；不要粘贴到聊天窗口。
 
-> 用户不会操作时：AI 逐步引导（开终端 → 粘贴命令 → 回车 → 复制输出），直到成功。**除复制粘贴外用户不做别的**。
+> token 可以按用户习惯复制；agent_key 属于私密能力，优先走 `key claim` 或安全文件传输，不走对话明文。
 
 ### 4.6 配置 MCP（AI 自己完成，🔒 需同意）
 1. 🔒 说明将把 yotta-memory 写入本智能体 MCP 配置并请用户同意；
@@ -394,6 +471,8 @@ yotta-memory doctor --json
 
 > MCP 工具集与 CLI 一致：remember / recall / search / forget / archive / reindex / export / import / profile；管理动作（init / config / token / lan / serve）不进 MCP，token 管理不远程暴露；MCP export/import 路径限记忆库内、distill 不支持 `--model`（仅本地 CLI）。
 
+> 工具分组（v0.15.0）：常驻场景用 `yotta-memory serve --stdio --tools core --agent-id <id> --agent-key-file <path>`，只暴露 `context / recall / search / remember`；需要诊断、维护、导入导出时用 `--tools full`。调用不属于当前分组的工具会返回明确提示，不会静默执行。
+
 ### 4.7 MCP 配置位置表
 | 智能体 | 常见 MCP 配置位置 |
 |---|---|
@@ -412,16 +491,36 @@ yotta-memory doctor --json
       "url": "http://<IP>:8787/mcp",
       "headers": {
         "Authorization": "Bearer <TOKEN>",
-        "X-Agent-Id": "<本智能体ID>"
+        "X-Agent-Id": "<本智能体ID>",
+        "X-Agent-Key": "<本智能体的 agent_key>"
       }
     }
   }
 }
 ```
 
+`X-Agent-Key` 的值来自该 AI 的宿主 key 文件 `<AI_HOME>/.yotta-memory-agent-key`。同机 / 共享文件系统先用 `key claim` 写入；不共享文件系统时由用户安全传输，不要把 key 发到对话里。配置文件写入前仍需获得用户同意。
+
+本机 stdio 配置使用显式参数，不写身份 env：
+```json
+{
+  "mcpServers": {
+    "yotta-memory": {
+      "command": "node",
+      "args": [
+        "<runtimeRoot>/current/bin/yotta-memory.js",
+        "serve", "--stdio", "--tools", "core",
+        "--agent-id", "<本智能体ID>",
+        "--agent-key-file", "<AI_HOME>/.yotta-memory-agent-key"
+      ]
+    }
+  }
+}
+```
+
 ### 4.9 验证连接（循环兜底）
 - 🔒 连接远程引擎前已获同意（4.5 / 4.6）→ 调一次 `recall` / `search` 确认能读到记忆 → 成功。
-- 失败：查 IP / 端口 / token 完整性 / 防火墙 / token 吊销；仍失败回 4.3。
+- 失败：查 IP / 端口 / token 完整性 / agent_key 是否匹配 / 是否已吊销 / 防火墙 / token 吊销；仍失败回 4.3。
 
 ### 4.10 复用
 - 成功后优先复用现有连接；失败（token 吊销等）再回 4.3。
@@ -431,7 +530,7 @@ yotta-memory doctor --json
 常见问题与避坑见 `references/faq.md`：
 - 类型选错 → 只提示不阻止；`forget` 后按正确类型重写；
 - 私密区加密 → `init` 默认加密（主口令+恢复钥匙），明文库 `migrate` 升级，`view` 平台口令解锁；
-- 多智能体权限 → FACT 公共、私密按 owner 隔离，需 `key authorize` / `view` 授权；
+- 多智能体权限 → FACT 公共、私密按 owner 隔离；用户授权后写 binding + pending，AI 用 `key claim` 领取到宿主目录；owner ID 不是认证，吊销后旧 key 立即失效；
 - 记忆找不到 → `config get` 查位置 → `reindex` → `recall` / `search`；
 - 忘记主口令 → 用恢复钥匙 `reset-password`；
 - 局域网 → 引擎 `lan enable` + `token new`，客户端配 url+token。

package/USER_GUIDE.md

@@ -12,6 +12,7 @@
 3.7 查看平台分页与检索优化（v0.8.1）
 3.8 可靠性基线：防覆盖、回收区与备份（v0.12.0）
 3.9 开工 doctor 与事务快照（v0.12.2）
+3.10 MCP 工具分组（v0.15.0）
 4. 便携记忆盘 · 记忆引擎主机篇（Linux / Windows）
 5. 智能体接入篇（本机 / 局域网其它主机）
 6. CLI 命令速查
@@ -31,9 +32,10 @@
 - **多智能体共享**：FACT 进公共区共享，PREF / BOUND / COMMIT 各自私密隔离。
 - **交接与团队协作**：项目级 `.yottamemory` 随仓库走，交接即恢复。
 - **便携记忆盘**：记忆装在固定主机上，本机与局域网其它主机共享同一份记忆（见第 4 / 5 篇）。
-- **越用越懂（v0.6.0）**：AI 按「记忆守则」主动捕获信号，`profile` 聚合画像、`context` 开工注入——用得越久越懂你。
+- **越用越懂（v0.14.0）**：AI 按「记忆守则」主动捕获信号，`context` 开工注入长期摘要、画像、近期走廊、边界、承诺与会话闭环契约——用得越久越懂你。
 - **自我学习 / 自我进化 / 自我提升（v0.8.0 + v0.9.0）**：`recall` 语义检索（同义词 / 拼音 / 字段加权 / 模糊，v0.9.0 可选本地 embedding 插件）+ `feedback` 使用反馈闭环 + `maintain` 规则层自组织 + `distill` 心理日志蒸馏——记忆系统会自己整理、提炼、演化。
 - **可靠性基线（v0.12.0 / v0.12.2）**：`init` 对已有库拒绝覆盖；`forget` 进回收区；`backup volumes/setup/status/ensure-daily/schedule/drill` 在用户确认真实独立卷后默认每日自动备份，并提供校验、恢复与恢复演练；`doctor` 开工检查风险，破坏性操作写入前自动创建事务快照。
+- **MCP 工具分组（v0.15.0）**：`serve --tools core` 只暴露 `context / recall / search / remember`，适合常驻；`--tools full` 提供完整诊断与维护工具。未指定时默认 `full`。
 
 ## 2. 安装（CLI + 技能）
 
@@ -81,16 +83,16 @@ yotta-memory config get                              # 查看记忆库位置
 - 想换记忆位置：`yotta-memory config set memory_home <目录>`，之后所有命令自动用新位置。
 - 项目级记忆：在项目目录里 `yotta-memory init --project`，该项目的智能体优先读项目级记忆。
 
-### 画像与开工上下文（v0.6.0）
+### 画像与开工上下文（v0.6.0 + v0.9.0 + v0.14.0）
 
 ```bash
 yotta-memory profile                          # 生成用户画像（写 private/<owner>/profile.md）
-yotta-memory context --limit 10 --budget 1800 # 生成开工上下文包（身份+铁律+画像+近期记忆+边界+承诺，预算控 token）
+yotta-memory context --limit 10 --budget 1800 # 生成开工上下文包（身份+铁律+画像+长期摘要+近期走廊+高价值补位+边界+承诺+闭环契约，预算控 token）
 yotta-memory iam <id> --name 元忆 --user 用户 --relationship 伙伴   # 自我档案扩展显示名/用户/关系
 ```
 
 - `profile` 引擎零推断：只按类型 / 主题 / 标签归组呈现原文，画像结论由 AI 内部形成，不当面贴标签。
-- `context` 是每次会话开工的主注入，替代裸 `recall`；无画像时自动生成一次或降级，不报错；`--budget` 控制近期记忆字符预算（token 恒定）。
+- `context` 是每次会话开工的主注入，替代裸 `recall`；长期摘要优先、近期走廊按时间取样、近期高价值补位按文件去重；无画像时自动生成一次或降级，不报错；`--budget` 控制动态记忆字符预算，长期摘要 / 身份 / 铁律 / 画像 / 边界 / 承诺 / 闭环契约必保（token 恒定）。
 - `remember --verify` 写后回读校验；`remember --no-hint` 关闭「疑似偏好，建议 PREF」的提示。
 
 ### 记忆库位置：本机智能体如何找到记忆
@@ -129,18 +131,19 @@ statement: 本周完成发布
 
 **用户查看平台（看所有 AI 的记忆）**
 
-`yotta-memory view` → 浏览器打开 http://127.0.0.1:8788 → 输入主口令解锁 → 浏览 / 搜索 / 导出全部记忆（含各 AI 私密）；也可在此**授权 / 吊销**某 AI 读取其私密、**重设口令**、**查看恢复钥匙**。口令只在本地内存派生，不落盘、不发远端；默认仅本机，远程需 `--host` 显式开启。
+`yotta-memory view` → 浏览器打开 http://127.0.0.1:8788 → 输入主口令解锁 → 浏览 / 搜索 / 导出全部记忆（含各 AI 私密）；也可在此**授权 / 吊销**某 AI 读取其私密、**重设口令**、**查看恢复钥匙**。点击「授权」后会弹窗展示只显示一次的 `agent_key`，请立即单独保存；引擎同时写临时 `keys/pending/<id>.key`，该 AI 新会话用 `key claim` 领取到自己的宿主目录，领取成功后 pending 删除。已绑定的 agent 需先「吊销」再授权，旧 key 随即校验失败。口令只在本地内存派生，不落盘、不发远端；默认仅本机，远程需 `--host` 显式开启。
 
 **AI 接入加密库**
 
-1. 该 AI 声明身份（`iam` / MCP 配置 `YOTTA_AGENT_ID`）。
-2. 用户在平台对其点一次「授权」→ 平台把该 AI 的 owner key 写入授权缓存（`keys/cache/<id>.key`，600 权限）。
-3. 之后该 AI 正常 `remember / recall / profile / context`，读写自动加解密；未授权时写私密会提示「需在用户平台授权」，公共 FACT 不受影响。
+1. 该 AI 登记身份（`iam` / MCP 启动参数 `--agent-id`，或 HTTP 请求头 `X-Agent-Id`）。
+2. 由用户执行一次 `yotta-memory view` → 在平台点「授权」→ 生成只展示一次的 `agent_key`，写入 `keys/bindings/<id>.key.agent` 和临时 `keys/pending/<id>.key`；不再写明文 owner key cache。高级用户也可自行执行 `yotta-memory key bind <id>`；AI 只负责提醒，不代执行。
+3. 该 AI 新会话执行 `yotta-memory key status <id>`；有 pending 就执行 `yotta-memory key claim <id>`，落到 `<AI_HOME>/.yotta-memory-agent-key`（需要指定位置时可加 `--to` / `--agent-key-file`）。之后 stdio MCP 用 `--agent-key-file <AI_HOME>/.yotta-memory-agent-key`，HTTP MCP 发送 `X-Agent-Key` 请求头，CLI 用 `--agent-key-file <AI_HOME>/.yotta-memory-agent-key`。
+4. 之后该 AI 正常 `remember / recall / profile / context`，读写自动加解密；未绑定 / key 缺失时会出现 `[YTM_MIGRATION_REQUIRED]` 迁移提示，公共 FACT 不受影响。
 
 **口令管理**
 
 - 重设口令：`yotta-memory reset-password`（输入当前口令），或忘口令时 `--recovery-key <恢复钥匙>`。
-- 吊销某 AI：`yotta-memory key revoke <id>`（立即失效）。
+- 吊销某 AI：`yotta-memory key revoke <id>`（立即失效，并清理 pending；旧 key 后续读取会校验失败）。
 - 注意：**口令即主密钥**，忘口令且丢失恢复钥匙 = 密文私密不可恢复（公共 FACT 仍在）。
 
 ## 3.6 自我学习 / 自我进化 / 自我提升（v0.8.0）
@@ -236,6 +239,16 @@ statement: 本周完成发布
 - `maintain --apply`、`consolidate --apply`、`merge`、`archive` 与 `--purge` 在写入前自动创建新的整库事务快照，并在 `.archive/audit-<日期>.jsonl` 记录 transaction / operation / snapshot。
 - 未配置独立备份目录、doctor critical 或快照失败时，命令直接拒绝执行，原记忆保持不变；`forget` 仍只移入 `.trash/`，不重复创建整库快照。
 
+## 3.10 运行时稳定入口与漂移诊断（v0.16.0 M2/M3）
+
+- `yotta-memory runtime install --from-current`：把当前 CLI 所属的完整包安装到 `<runtimeRoot>/versions/<版本>/`，并创建 `<runtimeRoot>/current` 稳定指针。
+- `yotta-memory runtime install <tarball|版本> [--force]`：安装本地 tarball，或从 npm 拉取指定版本；内容哈希写入 `runtime.json`。
+- `yotta-memory runtime use <版本> [--restart]`：切换到已安装版本；`--restart` 会尝试重启受管的 `lan` 服务，失败时自动把 current 切回旧版本。
+- `yotta-memory runtime rollback [--restart]`：回到上一个版本；`runtime list` / `runtime status` 查看版本、current 指针与漂移。
+- stdio MCP、`lan enable` 与备份调度只引用 `<runtimeRoot>/current/bin/yotta-memory.js`，不写死 `versions/<版本>/` 路径；升级只需 `runtime install` + `runtime use --restart`。
+- `yotta-memory doctor --runtime [--json]`：检查 CLI / current / `runtime.json` / MCP 配置 / 运行中 server / 技能副本 / 身份模式漂移；每项漂移给出实际版本、期望版本、修复命令和是否阻断。可用 `--mcp-config <文件>`、`--skill-dir <目录>` 显式补充检查目标。
+- MCP `initialize` / `server/discover` 的 `serverInfo` 返回 `runtimePath` / `identityMode` / `toolProfile`，宿主可显示实际执行的运行时路径与工具分组，不再只看配置里的版本。
+
 ## 4. 便携记忆盘 · 记忆引擎主机篇
 
 场景：记忆放在一台主机上（Linux / Windows 均可），本机直接 CLI 读写；局域网内其它主机上的 AI 智能体经 MCP 远程接入。引擎主机只需装 CLI，不需要装任何 AI 智能体。
@@ -255,6 +268,8 @@ yotta-memory init --dir /srv/yotta-memory               # 新库：初始化（
 
 **第 3 步：注册开机自启（可选，推荐）**
 
+`lan enable` 会先准备稳定运行时入口：没有 `<runtimeRoot>/current` 时自动执行 `runtime install --from-current`，然后把计划任务 / systemd / crontab 指向 `<runtimeRoot>/current/bin/yotta-memory.js`。如需手动准备，可先执行 `yotta-memory runtime install --from-current && yotta-memory runtime status`。
+
 ```bash
 # Windows：内置命令（优先计划任务；非管理员自动降级用户级 Startup 静默自启；
 # v0.6.3 起启动脚本自愈——启动文件被清理也会在开机时自动重建，无需手动处理）
@@ -287,7 +302,7 @@ yotta-memory token new --agent 我的智能体ID
 
 - 引擎地址：`http://<本机IP>:8787/mcp`
 - 该智能体的 token：`ytm_...`
-- 智能体 ID（对应 X-Agent-Id 请求头）
+- 智能体 ID（对应 X-Agent-Id 请求头）与该智能体的 agent_key（对应 X-Agent-Key 请求头）
 
 查本机 IP：Linux 运行 `hostname -I`（或 `ip a`）；Windows 运行 `ipconfig` 找「IPv4 地址」。防火墙：Linux 若启用了 ufw，执行 `sudo ufw allow 8787/tcp`；Windows 首次监听时允许放行。否则局域网其它主机连不进来。
 
@@ -311,21 +326,33 @@ yotta-memory remember FACT 主题 内容    # 智能体落盘
 
 智能体装上技能后（`SKILL.md`）会自动学会这套工作流，无需任何 MCP 配置。
 
-**方式二：stdio MCP（零常驻进程，智能体按需拉起 CLI）。** 在智能体 MCP 配置里加：
+**方式二：stdio MCP（零常驻进程，智能体按需拉起 CLI）。** 先让 AI 领取 agent_key：
+
+```bash
+yotta-memory key status <本智能体ID>
+yotta-memory key claim <本智能体ID>
+```
+
+领取成功后宿主目录出现 `<AI_HOME>/.yotta-memory-agent-key`；再由 MCP 宿主通过 `--agent-key-file` 读取该文件。然后在智能体 MCP 配置里加：
+
+`AI_HOME` 解析由 `key status` / `key claim` 共用：显式 `--to <目录>` 或 `--agent-key-file <文件>` > `YOTTA_MEMORY_AGENT_HOME` / `YOTTA_MEMORY_AGENT_KEY_FILE` > 宿主默认（Codex `$CODEX_HOME` 或 `~/.codex`、OpenCode `$XDG_CONFIG_HOME/opencode`、通用 `~/.<agent_id>`）；文件名固定为 `.yotta-memory-agent-key`。`key status` 会输出实际检查路径 `checked:` 与命中的发现规则 `discovery:`，即使文件暂不存在也可据此定位。
 
 ```json
 {
   "mcpServers": {
     "yotta-memory": {
       "command": "yotta-memory",
-      "args": ["serve", "--stdio"],
-      "env": { "YOTTA_AGENT_ID": "<该智能体唯一ID>" }
+      "args": [
+        "serve", "--stdio", "--tools", "core",
+        "--agent-id", "<该智能体唯一ID>",
+        "--agent-key-file", "<AI_HOME>/.yotta-memory-agent-key"
+      ]
     }
   }
 }
 ```
 
-本机接入不需要 token，也不需要启动 HTTP 服务；但**必须在配置里声明唯一的 `YOTTA_AGENT_ID`**（见下），否则写私密记忆会被拒。
+本机接入不需要网络 token，也不需要启动 HTTP 服务；但**必须用 `--agent-id` 声明唯一的智能体 ID，并用 `--agent-key-file` 指向自己的宿主 key 文件**，否则私密读写会被拒。身份环境变量已删除。
 
 **本机智能体装好技能后如何获取记忆存放位置？** 按优先级：`YOTTA_MEMORY_HOME` 环境变量 > `config set memory_home` 持久化的 `~/.yottamemory/config.json` > 默认 `~/.yottamemory`。AI 开工执行 `yotta-memory config get` 查看当前生效位置；记忆库移动后执行一次 `config set memory_home <新目录>` 即可。
 
@@ -333,13 +360,13 @@ yotta-memory remember FACT 主题 内容    # 智能体落盘
 
 1. 开工先 `yotta-memory whoami` 确认「我是谁」。
 2. 未登记 → 向用户确认一个**全局唯一** ID（建议 `<主机名>-<角色>`，别用 `dashu` / `codex` 这类易撞名），执行 `yotta-memory iam <id>`：引擎**强制唯一性**（被其它主机 / 来源占用会拒绝），并自动落一条「自我接入档案」PREF（owner=自己）。
-3. 本机多个 AI 智能体共用引擎时，**每个都要在它自己的 MCP 配置里声明唯一 `YOTTA_AGENT_ID`**（CLI 直连则每次带 `--agent <id>`），各自 `whoami` 各回各的、互不撞。
+3. 本机多个 AI 智能体共用引擎时，**每个都要在自己的 MCP 配置里用 `--agent-id` 声明唯一 ID，并用 `--agent-key-file` 指向自己的 key 文件**；HTTP 场景则在请求头写 `X-Agent-Id` + `X-Agent-Key`。CLI 直连每次带 `--agent <id> --agent-key <key>` 或 `--agent-key-file <文件>`。owner ID 单独存在时不构成认证。
 4. **禁止**从记忆里读到别人的 ID 就当自己的（比如看到「Kali 智能体 ID 为 dashu」就把自己当 dashu）；不确定先 `whoami` 再问用户，**禁止猜**。
 5. **不设则 owner 为空**：写私密记忆会被引擎拒绝（公共 FACT 不受影响），避免私密隔离退化。
 
 ### 5.2 局域网其它主机的 AI 智能体
 
-**第 1 步：向记忆引擎主机获取**：引擎 IP、端口（默认 8787）、本智能体的 token、智能体 ID。
+**第 1 步：向记忆引擎主机获取**：引擎 IP、端口（默认 8787）、本智能体的 token 与智能体 ID。若还没有 agent_key，由用户在引擎主机执行 `yotta-memory view` 授权；同机 / 共享文件系统时 AI 用 `key status` / `key claim` 领取到 `<AI_HOME>/.yotta-memory-agent-key`，不共享文件系统时由用户通过密码管理器或安全文件传输放到目标宿主目录。
 
 **第 2 步：配置 MCP**（可以让 AI 按 `SKILL.md` 引导自动完成；也可以手动在你的智能体 MCP 配置里加这段）：
 
@@ -350,7 +377,8 @@ yotta-memory remember FACT 主题 内容    # 智能体落盘
       "url": "http://<引擎主机IP>:8787/mcp",
       "headers": {
         "Authorization": "Bearer <TOKEN>",
-        "X-Agent-Id": "<本智能体ID>"
+        "X-Agent-Id": "<本智能体ID>",
+        "X-Agent-Key": "<本智能体宿主 key 文件中的 agent_key>"
       }
     }
   }
@@ -371,17 +399,18 @@ yotta-memory remember FACT 主题 内容    # 智能体落盘
 | `yotta-memory remember <类型> <主题> <内容> [--owner <id>] [--source <来源>] [--weight <0..>] [--verify] [--no-hint]` | 写入记忆（--source 来源；--weight 重要性权重；--verify 写后回读；--no-hint 关闭类型提示）|
 | `yotta-memory recall [关键词] [--type T] [--limit N] [--agent <id>] [--owner <id>] [--all] [--unsafe] [--explain] [--semantic] [--embedding <命令>] [--embedding-timeout N]` | 检索记忆（语义 + 效用分排序；可选本地 embedding 插件；读取分区过滤；越界读其它智能体私密默认拒绝，需 grant / identity=user / `--unsafe`）|
 | `yotta-memory profile [--owner <id>]` | 生成用户画像（零推断，写 `profile.md`）|
-| `yotta-memory context [--limit N] [--owner <id>] [--budget N] [--focus <关键词>] [--explain] [--embedding <命令>]` | 开工上下文包（身份+铁律+画像+任务相关记忆+近期记忆+边界+承诺；--focus 任务聚焦；--explain 输出 included/dropped 选择解释）|
+| `yotta-memory context [--limit N] [--owner <id>] [--budget N] [--focus <关键词>] [--explain] [--embedding <命令>]` | 开工上下文包（身份+铁律+画像+长期摘要+任务相关记忆+近期走廊+近期高价值+边界+承诺+会话闭环契约；--budget 控制动态记忆字符预算；--focus 任务聚焦；--explain 输出 included/dropped 选择解释）|
 | `yotta-memory forget <文件>` | 删除一条记忆 |
-| `yotta-memory doctor [--json]` | 开工可靠性检查（v0.12.2：根目录 / 密钥库 / 索引 / 身份 / 最近备份；严重异常时锁定破坏性写入）|
+| `yotta-memory doctor [--json] [--runtime] [--mcp-config <文件>] [--skill-dir <目录>]` | 开工可靠性检查（v0.12.2：根目录 / 密钥库 / 索引 / 身份 / 最近备份；严重异常时锁定破坏性写入；v0.16.0：`--runtime` 检查 CLI / current / MCP 配置 / 运行中 server / 技能副本漂移）|
 | `yotta-memory archive [--days 180] [--threshold 0.4]` | 归档旧记忆（分类型衰减效用分 + 年龄；immutable / BOUND 豁免；私密入 `.archive/private/<owner>/<type>/`）|
 | `yotta-memory reindex` | 重建索引 |
 | `yotta-memory export [--out 文件.json]` / `import <文件.json>` | 导出 / 导入 |
 | `yotta-memory config set <键> <值>` / `config get` | 记忆库位置与引擎参数（`memory_home` / `embedding_cmd` / `embedding_timeout` / `maintain_archived_utility` / `maintain_decay_halflife_<TYPE>` / `consolidate_*` 等）|
-| `yotta-memory whoami` | 查看当前智能体身份与登记状态（读 `YOTTA_AGENT_ID` / `X-Agent-Id`，不猜不默认）|
+| `yotta-memory whoami --agent <id>` | 查看当前显式身份与登记状态；身份不从环境变量读取 |
 | `yotta-memory iam <id> [--name <显示名>] [--user <用户名>] [--relationship <关系>] [--force]` | 登记本智能体唯一身份并自动落自我档案（`agents.json`，ID 必须唯一；可选扩展显示名 / 用户 / 关系）|
 | `yotta-memory token new --agent <id> [--force]` / `token list` / `token revoke --agent <id>` | 访问 token（同 ID 已被其它来源占用需 `--force` 覆盖）|
 | `yotta-memory serve [--port 8787] [--stdio] [--no-auth]` | 启动记忆引擎（--no-auth 关闭鉴权，仅限可信内网）|
+| `yotta-memory runtime list / install <tarball|版本> [--from-current] [--force] / use <版本> [--restart] / rollback [--restart] / status` | 运行时稳定入口（runtime.json + versions + current；安装 / 切换 / 回滚 / 查看漂移；`--restart` 尝试重启受管 server）|
 | `yotta-memory lan enable [--onstart] / disable / status` | 开机自启管理（Windows：计划任务/用户级 Startup 静默自启；Linux：systemd 用户单元/用户 crontab @reboot）|
 | `yotta-memory feedback <文件|主题> --useful|--useless [--reason <原因>] [--undo]` | 使用反馈（v0.8.0：useful/useless 调 weight/confidence/feedback_net；--undo 回滚）|
 | `yotta-memory maintain [--dry-run] [--apply] [--purge] [--threshold N] [--age N] [--dedup] [--dedup --apply] [--merge A,B]` | 记忆自组织（v0.8.0 + v0.10.0 自动合并）：归档 / 遗忘候选 / 置信度查重 / 自动合并；默认 dry-run，`--dedup` 与归档互斥 |
@@ -427,7 +456,7 @@ yotta-memory remember FACT 主题 内容    # 智能体落盘
 **确实需要读取其它智能体的私密记忆时（三种授权方式，满足任一即可）：**
 
 1. 显式授权 `grants.json`：在记忆库根目录写 `{"<你的agentID>": ["<对方agentID>"]}`；
-2. identity=user：以 `--agent user` / `--owner user` / 环境变量 `YOTTA_AGENT_ID=user` 读取；
+2. identity=user：以 `--agent user` / `--owner user` 读取，调用方仍需持有匹配的 agent_key；
 3. 显式放行 `--unsafe`：用户明确同意时使用。
 
 **协作纪律**：FACT 写入公共区共享；PREF / BOUND / COMMIT 只写自己的私密区；不主动读取其它智能体的私密记忆。