@yottameta/yotta-memory 0.13.1 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-memory",
-  "version": "0.13.1",
+  "version": "0.16.0",
   "description": "Yuanyi (元忆) — boundary-aware, file-based memory for AI agents. File-based, zero-dependency, diff/rollback-able; FACT/PREF/BOUND/COMMIT types (public shared / private isolated), user-level + project-level storage; v0.12 reliability baseline (init guard, trash-based deletion, independent-volume backup/list/doctor/restore, start-of-work doctor, transactional snapshots before destructive writes), v0.10 consolidation (periodic summaries with provenance, near-duplicate auto-merge, per-type decay, batch audit + rollback), v0.9 recall quality + context focus + optional local embedding plugin, plus v0.8 semantic search, feedback loop, self-organization and distillation.",
   "license": "MIT",
   "keywords": [

package/references/faq.md

@@ -6,10 +6,10 @@
 类型只在写入时提示、不阻止（FACT=公共 / PREF、BOUND、COMMIT=私密）。写错不影响已写入内容；想改类型可 `forget` 后按正确类型重写。不需要提示可用 `--no-hint`。
 
 ## 2. 私密区加密怎么用？
-`init` 默认初始化加密库（需主口令 + 恢复钥匙，请妥善保存）；明文库可用 `migrate` 升级为加密。私密区文件为 `.md.enc`，可 git 版本化。查看/授权用 `yotta-memory view`（口令解锁，浏览/授权/吊销 AI）。
+`init` 默认初始化加密库（需主口令 + 恢复钥匙，请妥善保存）；明文库可用 `migrate` 升级为加密。私密区文件为 `.md.enc`，可 git 版本化。查看/授权用 `yotta-memory view`（口令解锁，浏览/授权/吊销 AI）；授权时一次性展示的 `agent_key` 请立即保存，服务端同时写 `keys/pending/<id>.key` 供该 AI 新会话用 `key claim` 领取。出现 `[YTM_MIGRATION_REQUIRED]` 说明还有 agent 未绑定，请由你在 `view` 平台逐个点「授权」完成重新授权（AI 只提醒、不代执行）。
 
 ## 3. 多智能体权限怎么隔离？
-公共 FACT 所有智能体可读；PREF / BOUND / COMMIT 按 owner 物理隔离，其他智能体需显式授权（`key authorize <id>` 或 `view` 平台授权）。不授权读不到，也不会被别的智能体读到。
+公共 FACT 所有智能体可读；PREF / BOUND / COMMIT 按 owner 物理隔离，调用方必须持有匹配的 `agent_key`（用户执行 `key bind <id>`，或在 `view` 平台授权获得）。owner ID 单独存在不构成认证，不授权 / 无 key 读不到。私密操作缺 key 时会输出 `[YTM_MIGRATION_REQUIRED]`；授权完成后该标记消失。AI 新会话用 `key status <id>` 检查，pending 存在则 `key claim <id>` 落到 `<AI_HOME>/.yotta-memory-agent-key`；`AI_HOME` 默认规则由 claim / status 共用（显式 `--to` / `--agent-key-file` > `YOTTA_MEMORY_AGENT_HOME` / `YOTTA_MEMORY_AGENT_KEY_FILE` > Codex / OpenCode / 通用宿主默认），status 会显示 `checked` 与 `discovery`。吊销后旧 key 立即校验失败，需重新授权。
 
 ## 4. 记忆找不到了？
 先 `config get` 确认 `memory_home` 指向的库；再 `reindex` 重建索引（升级后索引版本变化会自动重建）；最后 `recall <关键词>` / `search <词>` 语义检索。跨项目记忆在项目级 `.yottamemory`。
@@ -18,16 +18,22 @@
 用初始化时保存的**恢复钥匙**：`yotta-memory reset-password`。没有恢复钥匙则私密区无法解锁（这是加密的预期行为），公共 FACT 不受影响。
 
 ## 6. 局域网（便携记忆盘）怎么连？
-引擎主机 `lan enable` 注册开机自启（Windows 计划任务 / Linux systemd）→ `token new --agent <id>` 生成 token；客户端配 `url: http://<主机IP>:8787/mcp` + `Authorization: Bearer <token>` + `X-Agent-Id: <id>`。`lan status` 查状态。
+引擎主机 `lan enable` 注册开机自启（Windows 计划任务 / Linux systemd）→ `token new --agent <id>` 生成 token；客户端配 `url: http://<主机IP>:8787/mcp` + `Authorization: Bearer <token>` + `X-Agent-Id: <id>` + `X-Agent-Key: <agent_key>`。同机 / 共享文件系统由 AI 用 `key status` / `key claim` 领取宿主 key；跨机不共享文件系统由用户通过密码管理器或安全文件传输放置，不走聊天明文。`lan status` 查状态。
+
+## 6.1 全局 CLI、MCP 或常驻服务版本不一致？
+先跑 `yotta-memory doctor --runtime`：它会列出 CLI、current、`runtime.json`、MCP 配置、运行中 server、技能副本与身份模式的漂移，并给出实际版本、期望版本、修复命令和是否阻断。用 `yotta-memory runtime install --from-current` 建立 `<runtimeRoot>/current` 稳定入口；升级用 `runtime install <tarball|版本>` + `runtime use <版本> --restart`，回滚用 `runtime rollback --restart`。`lan enable` 与备份调度只登记 `current/bin/yotta-memory.js`，不再写死版本目录。
 
 ## 7. MCP 工具没加载？
-检查客户端 `mcpServers` 已配置 yotta-memory（url + token）；改配置后重启/重载会话。本机直连可不配 MCP，直接用 CLI。
+检查客户端 `mcpServers` 已配置 yotta-memory（url + token + agent_key）；agent_key 应来自 `<AI_HOME>/.yotta-memory-agent-key` 或 MCP secret 注入，不把明文 key 写进对话。改配置后重启/重载会话。本机直连可不配 MCP，直接用 CLI。
+
+## 7.1 MCP 工具太多，想减少常驻工具？
+用 `serve --tools core` 启动，工具列表只保留 `context / recall / search / remember`；需要 `doctor`、`forget`、`maintain`、`distill` 等完整能力时改用 `--tools full`。未指定 `--tools` 时默认仍为 `full`，不会影响已有配置。
 
 ## 8. 记忆库在哪个目录？
 `yotta-memory config get` 查看；`config set memory_home <目录>` 改位置。项目级记忆用 `init --project`（存 `.yottamemory/` 随项目共享）。
 
 ## 9. 跨会话恢复上下文？
-开工运行 `yotta-memory context`（身份 + 画像 + 近期记忆 + 边界 + 承诺），需要细节再 `recall <关键词>`。
+开工运行 `yotta-memory context`（身份 + 铁律 + 画像 + 长期摘要 + 近期走廊 + 近期高价值 + 边界 + 承诺 + 会话闭环契约），需要细节再 `recall <关键词>`；摘要优先来自 `consolidate` 产物，收工前按闭环契约复盘并检查关键结论是否落盘。
 
 ## 10. 备份与迁移？
 优先使用 `backup create --dir <独立盘目录>` 创建整库备份；`backup list` 查看，`backup doctor` 校验 SHA-256，`backup restore <id> --to <新目录>` 恢复到新目录。备份默认拒绝与记忆库同卷。`export --out 文件.json` 仍可用于跨工具迁移；公共 FACT 是明文文件也可直接 git 备份。v0.12.2 起，破坏性操作也会在写入前自动创建事务快照。

package/references/protocol.md

@@ -29,7 +29,7 @@
 │   ├── facts/                # 公共 FACT 归档
 │   └── private/<owner>/<type>/  # 私密归档（PREF/BOUND/COMMIT，带 owner 防撞名）
 ├── index.json              # 公共 FACT 索引 + TF 打分（加密库只含公共条目）
-├── keys/                   # 加密库密钥库（v0.7）：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             # 智能体身份登记表（iam 写入，唯一性强制）
 └── README.md               # 记忆库说明
 ```
@@ -41,7 +41,9 @@
 ## 2.5 智能体身份（谁在写 / 谁在读）
 
 - **agent ID 必须全局唯一**：`iam <id>` 写入 `agents.json`（记忆库根目录），唯一性强制——ID 已被其它主机 / 来源（含远端 token 登记）占用则拒绝，确认是同一智能体才 `--force`。
-- **当次身份声明**：`whoami` / MCP `agent_info` 读「当次声明身份」——本机 `YOTTA_AGENT_ID`（stdio 由 MCP 配置 `env` 注入，CLI 用 `--agent`/环境变量）；远端 `X-Agent-Id` 请求头（经 token 绑定校验）。不猜不默认。
+- **当次身份声明（v0.16.0）**：`whoami` / MCP `agent_info` 读「当次显式身份」——CLI 用 `--agent` + `--agent-key/--agent-key-file`；stdio MCP 用 `--agent-id` + `--agent-key-file`；HTTP / 远程 MCP 用 `Authorization` + `X-Agent-Id` + `X-Agent-Key` 请求头（经 token 绑定校验）。身份 env 已删除，不接受环境变量 fallback。
+- **身份边界**：HTTP 鉴权模式缺少 `X-Agent-Id` 或 `X-Agent-Key` 直接 401；stdio 缺少 `--agent-id` / key 文件时，私密操作 fail-closed。CLI `--agent` 与 `--agent-id` 同时出现且不一致时拒绝启动。
+- **AI_HOME（v0.14.0）**：`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`。status 输出 `checked` 与 `discovery`。
 - **自我档案**：`iam` 自动写一条 PREF `subject=自我接入档案`（owner=自己），statement 为 `; ` 分隔的 key:value——`agent_id / host / memory_home / mcp_mode(stdio|http) / engine_url(仅远端) / token(仅远端；本机不存 token)`，可含 `agent_name / user_name / relationship`（`iam --name/--user/--relationship` 写入）。
 - **私密记忆必须有 owner**：PREF / BOUND / COMMIT 写入时未声明身份（owner 空）直接拒绝（公共 FACT 不受影响），从机制上防止「抄别人的 ID」。
 
@@ -92,7 +94,7 @@ immutable: false
 - **UMK（用户主密钥）**：主口令 PBKDF2-SHA256（600000 次迭代 + 随机 16B 盐，盐存 `keys/salt`）派生，永不落盘明文。
 - **Owner Key**：每 owner 随机 32B；被 UMK 包裹存 `keys/<owner>.key.enc`（头 `YTMKEY1`，AAD=`owner:<id>`），被恢复钥匙包裹存 `keys/<owner>.key.recovery`。
 - **恢复钥匙（RK）**：随机 32B；被 UMK 包裹存 `keys/recovery.key.enc`（AAD=`recovery`），初始化/迁移时向用户打印一次（base64）。忘口令时用户提供 RK → 解开 `*.key.recovery` → 重设口令。
-- **授权缓存**：平台授权后把 owner key 明文写 `keys/cache/<id>.key`（文件权限 0600，仅属主可读写）；AI 侧只持有自己这把缓存 key，UMK 永不接触 AI。`key revoke` = 删除缓存文件。
+- **agent_key 绑定**：由用户执行 `key bind <id>` 或在 `view` 平台授权，生成 32 字节 agent_key，只展示一次；owner key 由 agent_key 包裹写入 `keys/bindings/<id>.key.agent`（AES-256-GCM），同时写临时待领取文件 `keys/pending/<id>.key`。AI 新会话用 `key status <id>` / `key claim <id>` 领取到 `<AI_HOME>/.yotta-memory-agent-key`，需要时显式加 `--to` / `--agent-key-file`，claim 成功后删除 pending。stdio MCP 用 `--agent-key-file`，远程 MCP 用 `X-Agent-Key`，CLI 用 `--agent-key/--agent-key-file`；调用方必须提供 `agent_id + agent_key` 才能解出 owner key；UMK 永不接触 AI。`key revoke` 删除 binding 与 pending，旧 key 随即校验失败。`key list` 与私密操作失败时输出 `[YTM_MIGRATION_REQUIRED]`，AI 只负责把迁移步骤转达给用户。
 
 ### 密文记忆文件（`.md.enc`，头 `YTMENC1`）
 ```
@@ -110,10 +112,10 @@ magic "YTMIDX1" (7B) | nonce(12B) | tag(16B) | ciphertext(JSON: {version, update
 
 ### 命令扩展
 - `init [--encrypt|--no-encrypt]`：新建默认加密（需主口令，打印恢复钥匙）；`--no-encrypt` 明文降级。
-- `migrate`：明文私密区 → 密文（需主口令；打印恢复钥匙；当前智能体自动授权缓存）。
-- `view [--port 8788] [--host 127.0.0.1]`：用户查看平台（本机 Web；口令解锁 → 浏览/搜索/导出全部；授权/吊销 AI；重设口令；显示恢复钥匙）。
+- `migrate`：明文私密区 → 密文（由用户执行；需主口令；打印恢复钥匙；不写明文授权缓存，重新授权由用户在 `view` 平台逐个完成）。
+- `view [--port 8788] [--host 127.0.0.1]`：用户查看平台（本机 Web；口令解锁 → 浏览/搜索/导出全部；授权/吊销 AI；授权时展示一次性 key 并写 pending；重设口令；显示恢复钥匙）。
 - `reset-password [--password <当前> | --recovery-key <钥匙>] [--new-password <新>]`：重设主口令并重新包裹全部 owner 密钥。
-- `key list | authorize <id> | revoke <id>`：授权缓存管理（authorize 需主口令）。
+- `key list | bind <id> | rotate <id> | claim <id> --to <AI_HOME> | status <id> | revoke <id>`：agent binding 管理（bind/rotate 由用户执行，需主口令或恢复钥匙；claim/status 由 AI 读取 pending 并落到宿主目录；`authorize` 保留为 bind 的兼容别名）。`view` 的授权按钮只对未绑定 agent 生成一次性 key 和 pending，已绑定需先吊销。
 
 ## 4. 类型体系
 
@@ -139,7 +141,7 @@ magic "YTMIDX1" (7B) | nonce(12B) | tag(16B) | ciphertext(JSON: {version, update
 |---|---|
 | 公共 FACT | 始终可读 |
 | 当前 agent 自己的 private | 始终可读 |
-| 其它 agent 的 private | 默认拒绝（不返回内容）；需满足任一授权：① `grants.json` 显式授权记录 ② identity=user（`--agent user` / `--owner user` / `YOTTA_AGENT_ID=user`）③ 显式 `--unsafe` |
+| 其它 agent 的 private | 默认拒绝（不返回内容）；需满足任一授权：① `grants.json` 显式授权记录 ② identity=user（`--agent user` / `--owner user`）③ 显式 `--unsafe`；调用方仍须持有对应 agent_key |
 
 > **默认隔离行为（recall）**：不带 `--all` / `--owner <其它agent>` 时（即默认 recall），遇其它 agent 私密记忆**静默跳过**，不输出任何「有私密被拒」提示、也不报错（exit 0），不泄露私密存在性；仅当**显式跨智能体读取**（`--all` 或 `--owner <其它agent>`，且非 user/自身）且无授权命中时，才报错/警告：无可读命中 → 「检测到 N 条越界访问已被拒绝」+ exit 3；有可读命中 → 正常展示 + 追加警告。
 
@@ -158,7 +160,7 @@ magic "YTMIDX1" (7B) | nonce(12B) | tag(16B) | ciphertext(JSON: {version, update
 | `export [--out f.json]` | 导出全部记忆为 JSON |
 | `import <f.json>` | 从 JSON 导入（幂等）|
 | `profile [--owner <id>]` | 用户画像聚合（零推断，写 `private/<owner>/profile.md`；跨 owner 默认拒绝）|
-| `context [--limit N] [--owner <id>] [--budget N]` | 开工上下文包（stdout：身份 + 多智能体铁律 + 画像 + 近期记忆 + 边界 + 承诺；`--budget` 近期记忆字符预算）|
+| `context [--limit N] [--owner <id>] [--budget N] [--focus <关键词>] [--explain]` | 开工上下文包（stdout：身份 + 多智能体铁律 + 画像 + 长期摘要 + 任务相关记忆 + 近期走廊 + 近期高价值 + 边界 + 承诺 + 会话闭环契约；`--budget` 控制动态记忆字符预算）|
 | `iam <id> [--name] [--user] [--relationship] [--force]` | 登记身份 + 自我档案（可选扩展显示名 / 用户 / 关系）|
 
 
@@ -169,14 +171,34 @@ magic "YTMIDX1" (7B) | nonce(12B) | tag(16B) | ciphertext(JSON: {version, update
 - 权限：profile.md 属私密区（按 owner）；跨 owner 生成默认拒绝（exit 3），需 `--owner user` / `--unsafe` / grant 授权。
 - profile.md 为生成物，可随时重新生成；不进入 index.json。
 
-### context（开工上下文包，v0.6.0）
+### context（开工上下文包，v0.6.0 + v0.14.0）
 
-- `context [--limit N] [--owner <id>] [--budget N]`：stdout 输出开工上下文包（不落盘），含多智能体接入铁律段（可读 A/B/C、可写范围、违规红线）与五段：
+- `context [--limit N] [--owner <id>] [--budget N] [--focus <关键词>] [--explain]`：stdout 输出开工上下文包（不落盘），含多智能体接入铁律段（可读 A/B/C、可写范围、违规红线）与以下部分：
   1. 身份：agent_id / agent_name / user_name / relationship / host / memory_home（读自我档案）
   2. 用户画像摘要：profile.md（不存在则自动生成一次或降级跳过）
-  3. 近期记忆：按 importance（confidence × recency + updated + weight + immutable）排序前 N 条（默认 10），读取分区过滤；`--budget` 时按剩余字符预算逐条放行（身份/铁律/画像/边界/承诺 必保）
-  4. 边界提醒：BOUND 全列（可读范围内）
-  5. 承诺 / 锚点：COMMIT 全列（可读范围内）
+  2.5 长期理解摘要：优先加载 `consolidate` 产物（`source=consolidate` 或 tags `consolidate` + `summary`），默认最多 3 条，只注入 subject + statement；细节用 `recall` 下钻。
+  2.6 任务相关记忆（`--focus`）：任务关键词命中条目。
+  3. 近期走廊：按 `updated / created` 倒序取样，默认数量沿用 `--limit`，不受 utility 排序影响；排除摘要、BOUND / COMMIT 与已展示条目。
+  4. 近期高价值记忆（补位）：按 importance + utility 融合排序，补足未进入走廊 / focus 的条目，按文件去重。
+  5. 边界提醒：BOUND 全列（可读范围内）。
+  6. 承诺 / 锚点：COMMIT 全列（可读范围内）。
+  7. 本会话闭环契约：固定输出开工加载、进行中立即 `remember --verify`、收工前复盘检查 COMMIT / 会话小结。
+- `--budget`：控制 focus / 近期走廊 / 近期高价值等动态记忆的字符预算；身份、铁律、画像、长期摘要、边界、承诺与会话闭环契约必保。
+
+### 运行时稳定入口与诊断（v0.16.0 M2/M3）
+
+- `runtimeRoot` 默认位于 `~/.yottamemory/runtime`；布局为 `runtime.json` + `versions/<version>/` + `current`（Windows junction / Unix symlink）。
+- `runtime install --from-current` 从当前完整 npm 包安装；`runtime install <tarball|版本>` 安装 tarball 或拉取指定版本；`runtime use <version>` 切换 current；`runtime rollback` 切回 previous。
+- `runtime.json` 记录 `current / previous / versions[].treeHash / installedAt`；`runtime status` 报告 current 指针与版本目录漂移。
+- stdio MCP、`lan enable`、备份调度只引用 `<runtimeRoot>/current/bin/yotta-memory.js`；`runtime use --restart` 尝试重启受管 server，失败时把 current 切回旧版本。
+- `doctor --runtime` 检查 CLI / current / `runtime.json` / MCP 配置 / 运行中 server / 技能副本 / 身份模式；漂移项包含 actual / expected / fix / blocking。
+- MCP `initialize` / `server/discover` 的 `serverInfo` 返回 `runtimePath` / `identityMode`（`headers` / `stdio-args`）/ `toolProfile`（`core` / `full`）。
+
+### MCP 工具分组（v0.15.0）
+
+- `yotta-memory serve --stdio --tools core`：只暴露 `context / recall / search / remember`，适合常驻 MCP。
+- `yotta-memory serve --stdio --tools full`：暴露现有 16 个工具，适合诊断、维护、导入导出与自我学习操作。
+- 未指定 `--tools`：默认 `full`，保持旧配置兼容；`tools/list` 按当前分组返回，`tools/call` 越组调用会被拒绝并提示切换到 full。
 
 ### remember / iam 扩展（v0.6.0）
 

package/skill-manifest.json

@@ -3,7 +3,7 @@
   "slug": "yotta-memory",
   "name": "元忆",
   "package": "@yottameta/yotta-memory",
-  "version": "0.13.1",
+  "version": "0.16.0",
   "trust": "yottameta",
   "install": {
     "idempotent": true