@yottameta/yotta-memory 0.13.1 → 0.16.0

package/CHANGELOG.md

@@ -1,3 +1,67 @@
+## v0.16.0 (2026-09-18, M1 身份模型候选)
+
+**身份模型：请求边界即身份边界**
+
+- HTTP / 远程 MCP 身份只从请求头读取：`Authorization: Bearer <token>` + `X-Agent-Id` + `X-Agent-Key`；鉴权模式下缺少任一身份头直接返回 401，不再进入工具调用。
+- stdio MCP 身份只从显式启动参数读取：`serve --stdio --agent-id <id> --agent-key-file <path>`；不再读取 `YOTTA_AGENT_ID` / `YOTTA_MEMORY_AGENT_KEY` / `YOTTA_MEMORY_TRUST_ENV_AGENT`，并拒绝把裸 key 放进 `--agent-key` 命令行。
+- 删除身份环境变量解析；启动 HTTP / stdio MCP 时检测到旧身份 env 会以 `[YTM_IDENTITY_ENV_REMOVED]` 明确拒绝，并给出请求头 / 显式参数迁移指引，不静默降级。
+- 增加 per-call identity context，HTTP 与 stdio 的并发调用不再共享可变的进程级身份；新增三 agent 并发私密上下文隔离回归。
+- CLI 仍是 `--agent <id>` + `--agent-key` / `--agent-key-file`；`--agent-id` 与 `--agent` 同时出现且不一致时拒绝启动。
+- **运行时稳定入口（M2）**：新增 `runtime list` / `runtime install <tarball|版本> [--from-current] [--force]` / `runtime use <版本> [--restart]` / `runtime rollback [--restart]` / `runtime status`；`runtime.json` 记录 current / previous / 安装时间 / tree hash，`<runtimeRoot>/current` 作为 stable launcher。
+- `lan enable` 与备份调度先准备 runtime current，只登记 `<runtimeRoot>/current/bin/yotta-memory.js`；`runtime use --restart` 尝试重启受管 server，失败时把 current 切回旧版本。
+- **运行时诊断与握手（M3）**：新增 `doctor --runtime [--json] [--mcp-config <文件>] [--skill-dir <目录>]`，检查 CLI / current / runtime.json / MCP 配置 / 运行中 server / 技能副本 / 身份模式漂移，并为每项漂移输出实际版本、期望版本、修复命令和是否阻断。
+- MCP `initialize` 与 `server/discover` 的 `serverInfo` 新增 `runtimePath` / `identityMode` / `toolProfile`，宿主可直接读取实际执行的运行时路径、身份模式和工具分组。
+- 本条目为 0.16.0 的 M1-M3 候选；完成后才进入发布闸门。
+
+## v0.15.0 (2026-09-17)
+
+**MCP 工具分组：降低常驻工具面**
+
+- `serve` 新增 `--tools core|full`：`core` 暴露 `context / recall / search / remember`，`full` 保留现有 16 个工具；未指定时默认 `full`，保持向后兼容。
+- `tools/list` 按当前分组返回；`tools/call` 调非当前分组工具时返回可执行提示，要求切换到 `--tools full`。
+- OpenCode 集成默认使用 `core`，需要在智能体运行中减少工具常驻税；完整维护能力仍可按需启动 `full`。
+- 新增 `test/mcp-tool-profiles.test.js`，覆盖 core 列表、legacy / modern 分组一致性与越组调用提示。
+- 存储格式、AES-256-GCM、owner 隔离、agent_key 与权限判定不变。
+
+## v0.14.0 (2026-09-17)
+
+**上下文编排：让 AI 越用越懂用户；合并 O2 CLI 诊断修复**
+
+- `context` 新增「长期理解摘要」段：优先加载 `consolidate` 生成的周期摘要（`source=consolidate` / tags `consolidate` + `summary`），只注入 subject + statement，原文细节继续用 `recall` 下钻。
+- `context` 新增「近期走廊」段：按 `updated / created` 倒序取样，不受 utility 排序影响，让最近发生的事稳定进入开工上下文。
+- 原有近期记忆改为「近期高价值记忆（补位）」：保留 importance + utility 融合排序，并与摘要、focus、走廊按文件去重；摘要、身份、铁律、画像、边界、承诺与会话闭环契约不受 `--budget` 截断。
+- `context` 末尾新增「本会话闭环契约」：开工加载、进行中信号即 `remember --verify`、收工前复盘并检查 COMMIT / 会话小结是否落盘。
+- SKILL / protocol / USER_GUIDE / README 中英同步说明摘要优先、近期走廊、会话闭环与 `--budget` 语义。
+- 合并 O2 `0.13.3` CLI 诊断候选：非受信 ambient `YOTTA_AGENT_ID` 不再参与身份冲突判定，显式 `--agent` 优先；只有 `YOTTA_MEMORY_TRUST_ENV_AGENT=1` 时才接受环境身份。
+- `key status` / `key claim` 统一 AI_HOME 解析：显式 `--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` 与实际发现规则。
+- 顶层 usage 明确 `remember <type> <subject> <statement>` 与 `recall [关键词]`；`--query`、remember `--type` 等位置参数误用给出专门提示。
+- 新增 `test/context-cognition.test.js` 与 `test/cli-diagnostics.test.js`；合并后全量 `npm test` 108/108 PASS。
+- 不新增存储格式、不改变 AES-256-GCM、owner 隔离、agent_key 与权限判定；`consolidate` / `profile` / `distill` 语义保持兼容。
+
+## v0.13.2 (2026-09-16)
+
+**安全修复：调用者认证 + agent_key 绑定**
+
+- 私密操作不再把 owner ID 当身份：`whoami` / `context` / `profile` / `remember` / `recall` 需要显式 `--agent <id>` 或受信任的 MCP 环境身份。
+- 新增 `agent_key` capability：`key bind <id>` 生成并只展示一次 agent_key；owner key 由 `keys/bindings/<id>.key.agent` 使用 agent_key 包裹。
+- 删除对 `keys/cache/<id>.key` 明文 owner key 缓存的加载路径；legacy cache 只提示，不参与解密。
+- MCP 必须同时配置 `YOTTA_AGENT_ID` + `YOTTA_MEMORY_AGENT_KEY` + `YOTTA_MEMORY_TRUST_ENV_AGENT=1`；普通 shell 的 `YOTTA_AGENT_ID` 默认不可信。
+- 新增身份冲突、无 agent_key、错误 agent_key、冒充他人 ID、legacy cache 不加载等对抗性回归。
+- `key list` 与失败的私密操作输出 `[YTM_MIGRATION_REQUIRED]`：列出仍有私密数据且未绑定的 agent 与原因，供 AI 主动引导用户完成绑定迁移；`doctor` 同步给出提醒。仅存在 legacy cache、没有可迁移私密数据的 owner 单独提示，不进入迁移清单；授权决策仍由用户逐个确认。
+- 修复明文库 `migrate` 在身份解析处的崩溃，迁移后明确提示逐 agent `key bind`（不再写明文授权缓存）。
+- `view` 平台授权会一次性弹出并展示 `agent_key`，页面可复制保存；已有 binding 时返回 409 并提示先吊销，防止误换 key 打断在用的智能体。授权 / 吊销入口新增 owner ID 路径穿越校验。
+- `view` / `key bind` 授权后新增临时待领取文件 `keys/pending/<id>.key`；新增 `key status <id> --to <AI_HOME>` 与 `key claim <id> --to <AI_HOME>`，AI 可将 key 原子写入 `<AI_HOME>/.yotta-memory-agent-key`，回读校验后删除 pending。pending 不入 backup / export，避免备份包夹带明文 key。
+- `key revoke` 现在同时删除 binding 与 pending；私密读取不再跨操作缓存 owner key，长驻 MCP 进程在吊销后继续使用旧 key 会立即校验失败，必须由用户重新授权生成新 key。
+- 授权写入改为事务式：binding 写入后若 pending 交接文件写入失败，会回滚刚写入的 binding，避免产生“已绑定但用户拿不到 key”的孤儿授权。
+- 修复 MCP stdio 私密读写未使用宿主注入的 `YOTTA_MEMORY_AGENT_KEY` 的缺陷；远程 MCP 新增 `X-Agent-Key` 请求头，token 只负责连接鉴权，加密私密读写仍必须持有匹配的 agent_key。
+- `key bind` / `key revoke` / `token new` / `token revoke` / MCP `callTool` 统一拒绝非法 agent ID，阻止 `..` 或路径分隔符在密钥、token 与记忆路径入口被利用。
+- MCP `import` 在写入前校验私密条目 `owner`，拒绝路径穿越；`view` 平台校验 Host / Origin，并对页面与 API 响应关闭缓存、补安全响应头，阻止 DNS rebinding / 跨站请求面。
+- `key bind` 与 `view` 授权在 owner key 文件缺失时会先从 `keys/<owner>.key.recovery` 恢复原 key；原 key 与恢复文件都不可用且仍有密文时拒绝新建，避免旧数据被静默变成不可解密。
+- 恢复演练不再读取 legacy `keys/cache/*.key` 明文缓存；解密必须提供恢复钥匙或主口令。
+- 迁移边界：重新授权由用户在 `yotta-memory view` 平台逐个完成，AI 只转达 `[YTM_MIGRATION_REQUIRED]` 与操作步骤，不代替用户执行 `migrate` / `key bind`；`view` 授权确认框同步说明该操作属于用户侧。
+- 查看平台 HTML 移出内嵌字符串，改存 `assets/view.html`。
+- 发布前必须通过 security review；现有加密库需执行一次 `key bind` 迁移，明文库需先迁移加密。
+
 ## v0.13.1 (2026-09-13)
 
 - 清理发布文档与测试夹具中的本机专属盘符 / 路径示例，统一改为 `~/.yottamemory` 或占位路径。

package/README.md

@@ -9,7 +9,7 @@
 <p align="center">Boundary-aware, file-based memory for AI agents: let any agent live across sessions instead of a single conversation.</p>
 <p align="center">Start work with <code>recall</code> to restore context, <code>remember</code> important facts as you go, and archive at wrap-up; memories are Markdown files in the user's own directory — <b>readable, editable, auditable, rollback-able</b>, zero-dependency and ready to use.</p>
 <p align="center">FACT is shared, PREF / BOUND / COMMIT are privately isolated — <b>who may read what is decided by mechanism, not by AI self-discipline</b>; one memory store can be shared across agents, travels with the disk, and can be shared over LAN.</p>
-<p align="center">"Grows smarter the more you use it": <code>profile</code> aggregates a user profile (zero inference) + <code>context</code> builds a one-shot start-of-work package (identity + profile + recent memory + boundaries + commitments + wrap-up discipline), turning memory from "storage" into "a memory system that grows".</p>
+<p align="center">"Grows smarter the more you use it" (v0.14.0): <code>context</code> builds a one-shot start-of-work package with long-term summaries first (reusing <code>consolidate</code>) + a zero-inference <code>profile</code> + a time-ordered recent corridor + high-value backfill + boundaries + commitments + a session loop contract, turning memory from "storage" into "a memory system that grows".</p>
 <p align="center"><b>Mechanism-level encryption for the private zone</b>: AES-256-GCM envelope encryption + passphrase-derived master key + recovery key; <code>yotta-memory view</code> is a user-facing review platform (unlock with passphrase to see all AI memory); <code>migrate</code> converts plaintext → encrypted; <code>--no-encrypt</code> can downgrade. Cross-agent privacy upgrades from "discipline-level isolation" to "mechanism-level unreadable".</p>
 
 <p align="center">
@@ -23,6 +23,13 @@
 
 > 📖 The user-facing operations manual lives in [USER_GUIDE.md](USER_GUIDE.md).
 
+> 🆕 **v0.16.0 (identity model + stable runtime)**: identity is no longer read from environment variables. HTTP / remote MCP uses request headers `Authorization` + `X-Agent-Id` + `X-Agent-Key`; stdio MCP uses explicit `--agent-id` + `--agent-key-file`; CLI uses `--agent` + `--agent-key` / `--agent-key-file`. The new `runtime install --from-current` / `use` / `rollback` / `status` commands create a stable `<runtimeRoot>/current` launcher so managed MCP, autostart and backup tasks do not pin a version directory. `doctor --runtime` checks CLI / current / MCP config / running server / skill-copy drift, and MCP `serverInfo` returns `runtimePath` / `identityMode` / `toolProfile`.
+> 🆕 **v0.15.0 (MCP tool profiles)**: `serve --tools core|full` controls the exposed MCP surface. `core` keeps `context / recall / search / remember` resident; `full` keeps the existing 16 tools for diagnostics and maintenance. Omitting the flag keeps the previous `full` behavior for compatibility.
+
+> 🆕 **v0.14.0 (grows smarter + CLI diagnostics)**: `context` now loads long-term `consolidate` summaries first, samples a time-ordered recent corridor, keeps a deduplicated high-value backfill, and ends with a session loop contract (load at start, `remember --verify` during work, review before wrap-up). Identity, summaries, rules, profile, boundaries, commitments and the contract are not truncated by `--budget`; storage, encryption, owner isolation and permission checks are unchanged. This release also includes the CLI diagnostics work: explicit `--agent` wins over an untrusted ambient `YOTTA_AGENT_ID`; only `YOTTA_MEMORY_TRUST_ENV_AGENT=1` makes an environment identity authoritative. `key status` / `key claim` share one AI_HOME discovery rule (explicit `--to` / `--agent-key-file`, then `YOTTA_MEMORY_AGENT_HOME` / `YOTTA_MEMORY_AGENT_KEY_FILE`, then the Codex / OpenCode / generic host default) and `key status` always prints `checked` + `discovery`. The usage text now documents `remember <type> <subject> <statement>` and `recall [关键词]` directly.
+
+> 🆕 **v0.13.2 (security)**: owner ID is not an authentication credential. Private reads/writes now require an explicit `agent_key`; the user creates it through `yotta-memory view` (or by running `yotta-memory key bind <id>`), then configures MCP with `YOTTA_AGENT_ID` + `YOTTA_MEMORY_AGENT_KEY` + `YOTTA_MEMORY_TRUST_ENV_AGENT=1` (or CLI `--agent <id> --agent-key <key>` / `--agent-key-file <file>`). Authorization also writes a temporary `keys/pending/<id>.key`; a new AI session runs `key status <id>` / `key claim <id>` to store it at `<AI_HOME>/.yotta-memory-agent-key` and delete pending, while the popup key is the user's separate backup. Legacy `keys/cache/*.key` is no longer loaded. When an owner still needs rebinding, `key list` and failed private operations print `[YTM_MIGRATION_REQUIRED]` with the affected agent IDs; the AI relays the steps and the user re-authorizes in `yotta-memory view`, which shows the one-time `agent_key` and refuses to overwrite an existing binding until it is revoked; the old key then fails validation.
+
 > 🆕 **v0.12.2**: reliability closure — `yotta-memory doctor` checks the store, key material, index, identity registry and latest backup; `maintain --apply`, `consolidate --apply`, `merge`, `archive` and `--purge` create a transaction snapshot before writing and refuse to proceed if the snapshot fails.
 
 > 🆕 **v0.12.1**: installation and update docs now distinguish the engine CLI (`yotta-memory`) from the skill installer (`yotta-memory-install`), with copy-ready upgrade commands.
@@ -42,7 +49,7 @@ Most memory solutions treat "remembering" as a black box: data goes into a datab
 - **Memory is files** — each memory is a Markdown file with YAML frontmatter in the user's own directory. Any editor can view / edit / delete; git handles versioning and rollback; team sync and handoff use the same standard toolchain.
 - **Isolation is guaranteed by mechanism** — FACT goes to the public zone and is shared; PREF / BOUND / COMMIT go to the private zone, physically split per owner (`private/<owner>/<type>/`). Reads are partitioned by scope/owner; out-of-bound content is intercepted by the CLI and never returned (silently skipped by default; explicit unauthorized cross-read is denied with an error); all reads/writes go through CLI / MCP — direct shell access to library files is forbidden. Permissions are enforced by mechanism, not by AI "self-discipline".
 - **Zero dependency, ready to use** — no daemon, no database, no vector store; just Node.js. Install and use; data stays on the machine; deployable anywhere.
-- **Grows smarter (v0.6.0)** — `profile` aggregates a user profile (the engine infers nothing; it only groups verbatim text) + `context` generates a one-shot start-of-work package (identity + profile + recent memory + boundaries + commitments); the SKILL "memory discipline" injects rule layers (type red lines / trigger signals / know the user / bottom lines / host isolation) — rules and mechanisms only, no personality data; zero data out of the box.
+- **Grows smarter (v0.14.0)** — `context` generates a one-shot start-of-work package (identity + long-term summaries first + zero-inference profile + time-ordered recent corridor + high-value backfill + boundaries + commitments + session loop contract); long-term summaries reuse `consolidate` output. The SKILL "memory discipline" injects rule layers (type red lines / trigger signals / know the user / bottom lines / host isolation) — rules and mechanisms only, no personality data; zero data out of the box.
 - **Self-learning / self-evolving / self-improving (v0.8.0)** — `recall` semantic search (synonyms / pinyin full + initials / field weighting / fuzzy match, zero-dependency) with utility-score blended ranking; `feedback` explicit usage feedback loop (useful / useless adjusts weight / confidence / feedback_net); `maintain` rule-layer self-organization (unified utility score + age-based auto-archive / forget candidates / dedup, dry-run by default, immutable / BOUND exempt); `distill` psychological-log distillation (statistical summary / topic profile / knowledge map, optional `--model` external model enhancement).
 - **Compression & forgetting (v0.10.0) — memory that never bloats** — `consolidate` summarizes old, low-use memories on the same topic into one **provenance-carrying periodic summary** that stays in active memory (every original file is listed as provenance; originals move to `.archive/`; `--undo <batch>` restores everything); `maintain --dedup` scores near-duplicates and `--apply` auto-merges high-confidence groups; the utility recency component now decays **per type** (FACT slow / PREF medium / COMMIT task-like fast / BOUND never) so durable facts are not wiped by time and stale commitments step aside quickly; every batch is auditable via `consolidate --batches`.
 - **Reliability baseline (v0.12.0 / v0.12.2)** — `init` refuses to overwrite an existing store and `--attach` attaches instead; `forget` moves entries to `.trash/` with an audit record; `backup create / list / doctor / restore` backs up the store to an independent volume with a SHA-256 manifest and restores only to a new directory; `yotta-memory doctor` checks the store, key material, index, identity registry and latest backup, and destructive writes take a transaction snapshot first.
@@ -68,7 +75,7 @@ Memory is classified into four types; the type decides visibility:
 
 - **Three read states**: public FACT always readable; own private always readable; other agents' private is denied by default (content not returned).
 - **Physically isolated directories**: private memory lives at `private/<owner>/<type>/`; different agents' private files are physically separated; legacy flat `prefs/` `bounds/` `commits/` auto-migrate on `reindex`.
-- **Three authorization gates** (any one grants reading another's private): 1. explicit grant in `grants.json`; 2. identity=user (`--agent user` / `--owner user` / `YOTTA_AGENT_ID=user`); 3. explicit `--unsafe` (user explicitly authorized).
+- **Three authorization gates** (any one grants reading another's private): 1. explicit grant in `grants.json`; 2. identity=user (`--agent user` / `--owner user`); 3. explicit `--unsafe` (user explicitly authorized). The caller must still present the matching `agent_key`.
 - **Silent by default, explicit cross-read errors**: default recall silently skips other agents' private (no "there are N invisible private entries" leak); only explicit cross-agent reads (`--all` / `--owner <other>`) without authorization error / warn.
 - **`--agent <other>` does not cross**: it only declares identity for display; reading other agents' private still needs grant / identity=user / `--unsafe`.
 - **Isolation positioning**: scope: private guarantees semantic isolation between AIs; since v0.7 the private zone is mechanism-level confidentiality — files are AES-256-GCM envelope encrypted, so an AI without the owner key cannot decrypt them even if it reads the ciphertext; data sovereignty remains with the user, who can use `yotta-memory view` to unlock and view / export any memory file.
@@ -81,13 +88,13 @@ Each agent has a globally unique agent ID: it is the ownership key for private m
 - **Register (must be unique)**: `yotta-memory iam <id>` writes `agents.json` at the memory root, **enforcing uniqueness** — denied if the ID is already used by another host / source (including remote token registration); `--force` only when you confirm it is the same agent.
 - **Confirm identity**: `yotta-memory whoami` (remote MCP tool `agent_info`) reads the "declared identity of this session" — it never guesses or assumes.
 - **Self profile (forced to disk)**: `iam` auto-writes a PREF `subject=自我接入档案` (owner=self) with `; `-separated key:value: `agent_id / host / memory_home / mcp_mode / engine_url / token` (token not stored locally). Start work with `recall "自我接入档案"` to recover identity and connection info.
-- **No token locally**: local CLI / stdio direct connection bypasses the network and does not validate tokens; identity is declared via the agent's MCP `env.YOTTA_AGENT_ID`.
+- **No network token locally**: local CLI / stdio bypasses HTTP tokens, but private access still requires `agent_id + agent_key`; stdio MCP passes the key file with `--agent-id` + `--agent-key-file`, never through identity env.
 - **Private memory requires an owner**: writing PREF / BOUND / COMMIT without declaring identity is rejected (public FACT is unaffected), mechanically preventing ID spoofing.
 
-### Profile & start-of-work context (v0.6.0 + v0.9.0)
+### Profile & start-of-work context (v0.6.0 + v0.9.0 + v0.14.0)
 
 - **profile**: aggregates `private/<owner>/` PREF / BOUND / COMMIT verbatim, grouped by type + subject + tags, written to `profile.md`; the engine infers nothing — profile conclusions are formed internally by the AI per the "memory discipline", never pasted as labels.
-- **context**: one-shot start-of-work package — multi-agent integration rules + identity + user profile digest + optional task-focused memory (`--focus`) + recent memory (importance-sorted) + boundary reminders + commitments/anchors; supports `--budget` character budget and `--explain` selection trace.
+- **context**: one-shot start-of-work package — multi-agent integration rules + identity + long-term summaries first (`consolidate` output) + user profile digest + optional task-focused memory (`--focus`) + time-ordered recent corridor + deduplicated high-value backfill + boundary reminders + commitments/anchors + session loop contract; supports `--budget` for dynamic memory and `--explain` selection trace.
 - **Memory discipline**: SKILL.md embeds a rule layer (type red lines / proactive trigger capture / know-the-user three stages / psychological grounding & alignment / bottom lines / host isolation / anti-patterns).
 
 ### Retrieval: semantic search (v0.8.0 + v0.9.0 embedding)
@@ -122,11 +129,12 @@ Each agent has a globally unique agent ID: it is the ownership key for private m
 |---|---|
 | Wrong memory type? | Hint only; forget and rewrite; --no-hint to disable |
 | Private encryption? | init encrypts by default (master password + recovery key); migrate to encrypt a plaintext store |
-| Multi-agent isolation? | FACT public; PREF/BOUND/COMMIT per-owner, grant via key authorize / view |
+| Multi-agent isolation? | FACT public; PREF/BOUND/COMMIT per-owner + per-agent `agent_key`; the user binds once via `view` (or `key bind`) |
 | Memory not found? | config get -> reindex -> recall/search |
 | Lost master password? | reset-password with recovery key |
 | LAN connect? | lan enable + token new; client url+token |
 | MCP not loaded? | Check mcpServers + restart; use CLI directly |
+| Version mismatch? | Run `yotta-memory doctor --runtime` and apply the repair command for each drift |
 | Where is the store? | config get; project-level .yottamemory |
 | Cross-session resume? | Run context + recall at session start |
 | Backup / migrate? | export / import |
@@ -220,9 +228,12 @@ Recorded: ~/.yottamemory/facts/2026-09-01-0001.md
 # Start-of-work context (yotta-memory context)
 ## 1. Identity
 ## 2. User profile summary
-## 3. Recent memories (top 10 by activity)
-## 4. Boundaries (BOUND)
-## 5. Commitments / anchors (COMMIT)
+## 2.5 Long-term understanding summaries
+## 3. Recent corridor (time-ordered)
+## 4. Recent high-value backfill
+## 5. Boundaries (BOUND)
+## 6. Commitments / anchors (COMMIT)
+## 7. Session loop contract
 ```
 
 ## Upgrade
@@ -268,9 +279,9 @@ Optional post-upgrade self-check: `yotta-memory config get` (confirm `memory_hom
 | `yotta-memory remember <type> <subject> <statement> [--owner <id>] [--source <src>] [--weight <0..>] [--verify] [--no-hint]` | Write a memory (same subject+statement auto-updates; --owner marks ownership; --source records origin; --weight importance, dedup takes max; --verify read-back; --no-hint disables type hints) |
 | `yotta-memory recall [keywords] [--type T] [--limit N] [--agent <id>] [--owner <id>] [--all] [--unsafe] [--explain] [--semantic] [--embedding <cmd>] [--embedding-timeout N]` | Search memory (semantic + utility ranking; optional local embedding plugin; partitioned reads; cross-reading other agents' private is denied by default, needs grant / identity=user / `--unsafe`; project-level priority) |
 | `yotta-memory profile [--owner <id>]` | Generate a user profile (aggregates `private/<owner>` verbatim, zero inference, writes `profile.md`; cross-owner denied by default) |
-| `yotta-memory context [--limit N] [--owner <id>] [--budget N] [--focus <text>] [--explain] [--embedding <cmd>]` | Generate the start-of-work package (identity + multi-agent rules + profile + task-focused memory + recent memory + boundaries + commitments; --budget caps chars, --focus adds task relevance, --explain shows included/dropped) |
+| `yotta-memory context [--limit N] [--owner <id>] [--budget N] [--focus <text>] [--explain] [--embedding <cmd>]` | Generate the start-of-work package (identity + rules + profile + long-term summaries + task-focused memory + recent corridor + high-value backfill + boundaries + commitments + session loop contract; --budget caps dynamic memory, --focus adds task relevance, --explain shows included/dropped) |
 | `yotta-memory forget <file>` | Delete a memory (by type-dir path or file name) |
-| `yotta-memory doctor [--json]` | Start-of-work reliability check (store / key material / index / identity / latest backup; critical issues lock destructive writes) |
+| `yotta-memory doctor [--json] [--runtime] [--mcp-config <file>] [--skill-dir <dir>]` | Start-of-work reliability check (store / key material / index / identity / latest backup; critical issues lock destructive writes); `--runtime` checks CLI / current / MCP config / running server / skill-copy drift |
 | `yotta-memory archive [--days 180] [--threshold 0.4]` | Archive old memory (decay-blended utility + age; immutable / BOUND exempt; private to `.archive/private/<owner>/<type>/`) |
 | `yotta-memory reindex` | Rebuild the index (after manually editing .md) |
 | `yotta-memory export [--out f.json]` / `import <f.json>` | Export / import |
@@ -278,7 +289,7 @@ Optional post-upgrade self-check: `yotta-memory config get` (confirm `memory_hom
 | `yotta-memory whoami` | Show the current agent identity and registration status |
 | `yotta-memory iam <id> [--name <name>] [--user <user>] [--relationship <rel>] [--force]` | Register this agent's unique identity and auto-write the self profile (`agents.json`, ID must be unique) |
 | `yotta-memory token new --agent <id> [--force]` / `token list` / `token revoke --agent <id>` | Create / list / revoke access tokens for agents (registered at `.server/tokens.json`) |
-| `yotta-memory serve [--host 0.0.0.0] [--port 8787] [--no-auth] [--stdio]` | Start the MCP memory engine (streamable HTTP LAN / --stdio local zero-process mode; Bearer token + X-Agent-Id auth) |
+| `yotta-memory serve [--host 0.0.0.0] [--port 8787] [--no-auth] [--stdio]` | Start the MCP memory engine (streamable HTTP LAN / --stdio local zero-process mode; Bearer token + X-Agent-Id + X-Agent-Key auth) |
 | `yotta-memory lan enable [--onstart] / disable / status` | Autostart management (Windows: scheduled task, default ONLOGON, --onstart needs admin, non-admin auto-degrades to user-level Startup; Linux: systemd user unit, falls back to user crontab @reboot) |
 | `yotta-memory maintain [--dry-run] [--apply] [--purge] [--threshold N] [--age N] [--dedup] [--dedup --apply] [--merge A,B]` | Self-organization: archive / forget candidates / confidence-scored dedup / auto-merge high-confidence groups; dry-run by default; `--dedup` is mutually exclusive with archiving |
 | `yotta-memory consolidate [--min-age N] [--min-idle N] [--max-utility N] [--min-group N] [--period N] [--type T] [--model <cmd>] [--apply] [--undo <batch>] [--batches]` | Periodic-summary compression (v0.10.0): group old idle low-value memories into one traceable summary and archive the originals; dry-run by default; `--undo <batch>` rolls a batch back; `--batches` lists batches |
@@ -300,7 +311,9 @@ yotta-memory recall --type FACT --limit 10
 
 Environment variables:
 - `YOTTA_MEMORY_HOME`: overrides the user-level store directory (default `~/.yottamemory/`).
-- `YOTTA_AGENT_ID` / `AGENT_ID`: current agent ID (local identity declaration; participates in read-partition decisions; private memory requires an owner, undeclared is rejected).
+- `YOTTA_MEMORY_AGENT_HOME` / `YOTTA_MEMORY_AGENT_KEY_FILE`: explicit AI host directory / key file overrides for `key status` and `key claim`; command-line `--to` / `--agent-key-file` take precedence.
+
+Identity environment variables (`YOTTA_AGENT_ID`, `AGENT_ID`, `YOTTA_MEMORY_AGENT_KEY`, `YOTTA_MEMORY_TRUST_ENV_AGENT`) are no longer supported. The CLI ignores them; HTTP / stdio MCP startup rejects them so a stale host configuration cannot silently keep using the old model.
 
 ## After the agent is wired up
 
@@ -311,20 +324,43 @@ Once the skill is installed into an agent, SKILL.md teaches it the workflow auto
 The store can live on any host or disk (= the memory engine) and be reached by agents on other LAN hosts:
 
 - **Local direct**: CLI reads/writes directly, no token;
-- **Remote**: the engine host runs `yotta-memory serve` (or registers `lan enable` autostart); remote agents connect via MCP with `url + token`.
-- **Local zero-process**: local MCP clients can use `serve --stdio` to launch the CLI on demand (no resident process).
+- **Remote**: the engine host runs `yotta-memory serve` (or registers `lan enable` autostart); remote agents connect via MCP with `url + token + agent_key`. Same-host / shared-filesystem agents use `key claim`; cross-host setups without a shared filesystem require the user to transfer the host key securely.
+- **Local zero-process**: local MCP clients can use `serve --stdio --agent-id <id> --agent-key-file <path>` to launch the CLI on demand (no resident process).
+
+```json
+{
+  "mcpServers": {
+    "yotta-memory": {
+      "command": "node",
+      "args": [
+        "<runtimeRoot>/current/bin/yotta-memory.js",
+        "serve", "--stdio", "--tools", "core",
+        "--agent-id", "<this-agent-id>",
+        "--agent-key-file", "<AI_HOME>/.yotta-memory-agent-key"
+      ]
+    }
+  }
+}
+```
 
 ### Engine side (the host where memory lives)
 
 1. Initialize or attach to the store (see CLI usage).
-2. Generate an independent token for each agent that needs access:
+2. Install or refresh the stable runtime entry:
+   ```bash
+   yotta-memory runtime install --from-current
+   yotta-memory runtime status
+   yotta-memory doctor --runtime
+   ```
+   > `lan enable` and backup scheduling call the same runtime preparation automatically and only register `<runtimeRoot>/current/bin/yotta-memory.js`.
+3. Generate an independent token for each agent that needs access:
    ```bash
    yotta-memory token new --agent <agent-id>     # printed once, e.g. ytm_... (--force if the ID is taken by another source)
    yotta-memory token list                        # list registered agents
    yotta-memory token revoke --agent <agent-id>   # revoke
    ```
    > New tokens take effect immediately; no service restart needed.
-3. Start the service (default listens on 0.0.0.0:8787, Bearer token + X-Agent-Id auth) — temporary run or register autostart:
+4. Start the service (default listens on 0.0.0.0:8787, Bearer token + X-Agent-Id + X-Agent-Key auth) — temporary run or register autostart:
    ```bash
    yotta-memory serve                          # temporary foreground
    yotta-memory lan enable                     # register autostart (Windows: scheduled task / user-level Startup; Linux: systemd user unit / user crontab)
@@ -336,7 +372,14 @@ The store can live on any host or disk (= the memory engine) and be reached by a
 
 ### Client side (remote agent)
 
-Register the connection in the agent's MCP config (`url` + two headers):
+Before registering the connection, confirm the agent has claimed its key:
+
+```bash
+yotta-memory key status <agent-id>
+yotta-memory key claim <agent-id>
+```
+
+If the engine and the agent do not share a filesystem, `key claim` cannot read the remote pending file directly; the user must transport the key through a password manager or a secure file transfer into the agent host directory. Then register the connection (`url` + three headers):
 
 ```json
 {
@@ -345,14 +388,15 @@ Register the connection in the agent's MCP config (`url` + two headers):
       "url": "http://<engine-host-ip>:8787/mcp",
       "headers": {
         "Authorization": "Bearer <TOKEN>",
-        "X-Agent-Id": "<this-agent-id>"
+        "X-Agent-Id": "<this-agent-id>",
+        "X-Agent-Key": "<agent_key from this agent's host key file>"
       }
     }
   }
 }
 ```
 
-Once connected, MCP tools (remember / recall / search / context / doctor / forget / archive / reindex / export / import / agent_info) read/write memory and confirm identity; management actions (init / config / token / lan / serve) are not exposed via MCP, and token management is never exposed remotely. MCP `export` / `import` paths are restricted inside the memory root, MCP `distill` does not support `--model`, and MCP never accepts a raw embedding command from remote callers — the local embedding plugin must be configured on the engine host with `config set embedding_cmd`. `X-Agent-Id` must match the token's registered agent; read-partition rules are the same as the CLI (FACT public-readable, PREF / BOUND / COMMIT private).
+Once connected, MCP tools (remember / recall / search / context / doctor / forget / archive / reindex / export / import / agent_info) read/write memory and confirm identity; management actions (init / config / token / lan / serve) are not exposed via MCP, and token management is never exposed remotely. MCP `export` / `import` paths are restricted inside the memory root, MCP `distill` does not support `--model`, and MCP never accepts a raw embedding command from remote callers — the local embedding plugin must be configured on the engine host with `config set embedding_cmd`. `X-Agent-Id` must match the token's registered agent, and encrypted private reads/writes additionally require the matching `X-Agent-Key`; read-partition rules are the same as the CLI (FACT public-readable, PREF / BOUND / COMMIT private).
 
 ### Location persistence
 

package/README.zh-CN.md

@@ -9,7 +9,7 @@
 <p align="center">元忆 —— 有权限边界的文件式智能体记忆：让任何 AI 智能体活过会话，而不是只活在单次对话里。</p>
 <p align="center">开工 <code>recall</code> 恢复上下文、重要信息 <code>remember</code> 落盘、收工归档；记忆是落在用户自己目录里的 Markdown 文件——<b>可读、可改、可审计、可回滚</b>，零依赖、即装即用。</p>
 <p align="center">FACT 共享、PREF / BOUND / COMMIT 私密隔离——<b>谁该读、谁不该读，由机制而非 AI 自觉决定</b>；一份记忆可跨智能体共用，记忆库随盘走、局域网可共享。</p>
-<p align="center">「越用越懂」：<code>profile</code> 聚合用户画像（零推断）+ <code>context</code> 一键开工上下文包（身份 + 画像 + 近期记忆 + 边界 + 承诺 + 收工纪律），记忆从「存储」成长为「会成长的记忆系统」。</p>
+<p align="center">「越用越懂（v0.14.0）」：<code>context</code> 一键开工上下文包——长期理解摘要优先（复用 <code>consolidate</code>）+ <code>profile</code> 用户画像（零推断）+ 近期走廊（按时间）+ 近期高价值补位 + 边界 + 承诺 + 会话闭环契约，记忆从「存储」成长为「会成长的记忆系统」。</p>
 <p align="center"><b>私密区机制级加密</b>：AES-256-GCM 信封加密 + 口令派生主密钥 + 恢复钥匙；<code>yotta-memory view</code> 用户查看平台（口令解锁看全部 AI 记忆）；<code>migrate</code> 明文→密文迁移；<code>--no-encrypt</code> 可降级。跨 AI 私密从「纪律层隔离」升级为「机制层不可解」。</p>
 
 <p align="center">
@@ -23,6 +23,13 @@
 
 > 📖 面向用户的操作手册见 [USER_GUIDE.md](USER_GUIDE.md)。
 
+> 🆕 **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`。新增 `runtime install --from-current` / `use` / `rollback` / `status`，创建 `<runtimeRoot>/current` 稳定入口，受管 MCP、自启与备份任务不再写死版本目录。`doctor --runtime` 检查 CLI / current / MCP 配置 / 运行中 server / 技能副本漂移；MCP `serverInfo` 返回 `runtimePath` / `identityMode` / `toolProfile`。
+> 🆕 **v0.15.0（MCP 工具分组）**：`serve --tools core|full` 控制 MCP 工具暴露面。`core` 常驻 `context / recall / search / remember`；`full` 保留现有 16 个诊断与维护工具。未指定参数时默认 `full`，保持现有配置兼容。
+
+> 🆕 **v0.14.0（越用越懂 + CLI 诊断）**：`context` 新增「长期理解摘要」段（优先加载 `consolidate` 产物）+「近期走廊」段（按 updated / created 倒序）+「本会话闭环契约」（开工加载、进行中立即 `remember --verify`、收工前复盘）；原有近期记忆改为「近期高价值记忆（补位）」，与摘要 / focus / 走廊按文件去重。身份、长期摘要、铁律、画像、边界、承诺与闭环契约不受 `--budget` 截断；不改变存储、加密、owner 隔离与权限判定。本版同时合并 CLI 诊断修复：显式 `--agent` 优先于非受信 ambient `YOTTA_AGENT_ID`；只有 `YOTTA_MEMORY_TRUST_ENV_AGENT=1` 时环境身份才参与判定。`key status` / `key claim` 共用 AI_HOME 发现规则（显式 `--to` / `--agent-key-file` > `YOTTA_MEMORY_AGENT_HOME` / `YOTTA_MEMORY_AGENT_KEY_FILE` > Codex / OpenCode / 通用宿主默认），`key status` 始终输出 `checked` 与 `discovery`。usage 直接列出 `remember <type> <subject> <statement>` 与 `recall [关键词]`。
+
+> 🆕 **v0.13.2（安全）**：owner ID 不是认证凭证。私密读写必须持有 `agent_key`：由用户执行 `yotta-memory view` 授权（或自行运行 `yotta-memory key bind <id>`），再配置 MCP 注入 `YOTTA_AGENT_ID` + `YOTTA_MEMORY_AGENT_KEY` + `YOTTA_MEMORY_TRUST_ENV_AGENT=1`（CLI 用 `--agent <id> --agent-key <key>` 或 `--agent-key-file <文件>`）。授权同时写临时 `keys/pending/<id>.key`，AI 新会话用 `key status <id>` / `key claim <id>` 领取到 `<AI_HOME>/.yotta-memory-agent-key` 后删除 pending；弹窗 key 供用户单独备份。legacy `keys/cache/*.key` 不再加载。仍有 owner 需要重新绑定时，`key list` 与失败的私密操作会输出 `[YTM_MIGRATION_REQUIRED]` 并列出受影响 agent；AI 只提醒步骤，由用户在 `yotta-memory view` 逐个授权；平台一次性展示 `agent_key`，已有 binding 时需先「吊销」再重新授权，旧 key 随即校验失败。
+
 > 🆕 **v0.12.2**：可靠性收口——新增 `yotta-memory doctor` 开工检查；`maintain --apply`、`consolidate --apply`、`merge`、`archive` 与 `--purge` 在写入前自动创建事务快照，快照失败或严重异常时拒绝写入。
 
 > 🆕 **v0.12.1**：安装与更新文档明确区分引擎 CLI（`yotta-memory`）和技能安装器（`yotta-memory-install`），并补齐可直接复制的升级命令。
@@ -46,7 +53,7 @@
 - **记忆就是文件**：每条记忆是一个带 YAML frontmatter 的 Markdown 文件，放在用户自己的目录里。任何编辑器都能看、能改、能删；git 直接做版本管理与回滚，团队同步与交接走同一条标准工具链。
 - **隔离由机制保证**：FACT 进公共区共享，PREF / BOUND / COMMIT 进私密区、按 owner 物理分目录（`private/<owner>/<type>/`）。读取按 scope/owner 分区过滤，越界内容由 CLI 拦截、永不返回（默认静默跳过；显式跨读无授权报错拒绝）；读写一律走 CLI / MCP，禁止 shell 直读写库文件——权限由机制把关，不依赖 AI 的「自觉」。
 - **零依赖、即装即用**：无守护进程、无数据库、无向量库，只需 Node.js。安装即用，数据留在本机，任何机器都能部署。
-- **越用越懂（v0.6.0）**：`profile` 聚合用户画像（引擎零推断，只归组原文）+ `context` 一键生成开工上下文包（身份 + 画像 + 近期记忆 + 边界 + 承诺）；SKILL「记忆守则」注入规则层（类型红线 / 触发信号 / 了解用户 / 底线 / 宿主隔离），只注入规则与机制、不注入人格数据，出厂零数据。
+- **越用越懂（v0.14.0）**：`context` 一键生成开工上下文包——长期理解摘要优先（复用 `consolidate` 的周期摘要）+ `profile` 聚合用户画像（引擎零推断，只归组原文）+ 近期走廊（按更新时间取样）+ 近期高价值补位 + 边界 + 承诺 + 会话闭环契约；SKILL「记忆守则」注入规则层（类型红线 / 触发信号 / 了解用户 / 底线 / 宿主隔离），只注入规则与机制、不注入人格数据，出厂零数据。
 - **自我学习 / 自我进化 / 自我提升（v0.8.0）**：`recall` 语义检索（同义词 / 拼音全拼+首字母 / 字段加权 / 模糊匹配，零依赖）+ 效用分融合排序；`feedback` 显式使用反馈闭环（useful / useless 调整 weight / confidence / feedback_net，越用越懂）；`maintain` 规则层自组织（统一效用分 + 年龄自动归档 / 遗忘候选 / 去重，默认 dry-run，immutable / BOUND 豁免）；`distill` 心理日志蒸馏（统计摘要 / 主题画像 / 知识地图，可选 `--model` 外部模型增强）。
 - **压缩遗忘（v0.10.0）——记忆越用越精简**：`consolidate` 周期摘要压缩——把超龄 + 长期闲置 + 低效用的同主题旧记忆归纳成 **1 条带溯源的摘要**（每条原文路径都写在正文里）留在活跃区，原文整体进 `.archive/`，`--undo <batch>` 一键回滚；`maintain --dedup` 给近重复打分（≥0.85 高置信自动合并 / 0.65–0.85 建议手动），`--apply` 批量合并同归属重复组；时效分量改**分类型衰减**（FACT 慢 / PREF 中 / COMMIT 任务类快 / BOUND 永不衰减）——持久事实不被时间抹掉，过期承诺快速让位；每一步写批次审计（`--batches` 可查）。
 - **可靠性基线（v0.12.0 / v0.12.2）**：`init` 遇到已有记忆库默认拒绝覆盖（`--attach` 用于接入）；`forget` 先移入 `.trash/` 并写删除审计；`backup create / list / doctor / restore` 支持独立盘备份、SHA-256 清单校验、恢复默认只写新目录；`yotta-memory doctor` 检查根目录 / 密钥库 / 索引 / 身份 / 最近备份，破坏性操作在写入前自动创建事务快照。
@@ -65,10 +72,10 @@
 | **双级存储** | 用户级 `~/.yottamemory/`（跨项目）+ 项目级 `.yottamemory/`（随项目共享 / 交接）|
 | **检索与生命周期** | 语义检索（v0.8.0：同义词 / 拼音 / 字段加权 / 模糊，零依赖）+ 效用分融合排序；统一效用分（盖棺分）规则层自动归档 / 遗忘候选 / 去重（`maintain`，默认 dry-run），记忆库越用越精简 |
 | **压缩遗忘（v0.10.0）** | `consolidate` 周期摘要压缩（旧记忆 → 带溯源摘要 + 原文归档，可回滚）+ 近重复自动合并（置信度 + `--apply`）+ 分类型衰减（FACT 730 / PREF 365 / COMMIT 90 天半衰，BOUND 不衰减）+ 批次审计（`--batches` / `--undo`），长期使用不膨胀、主题不丢 |
-| **越用越懂（v0.6.0）** | `profile` 画像聚合（零推断）+ `context` 开工上下文包（身份 / 画像 / 近期记忆 / 边界 / 承诺）+ SKILL「记忆守则」规则层，记忆随使用成长 |
+| **越用越懂（v0.14.0）** | `context` 长期摘要优先 + `profile` 画像聚合（零推断）+ 近期走廊（按时间）+ 近期高价值补位 + 边界 / 承诺 + 会话闭环契约，记忆随使用成长 |
 | **生态分发** | GitHub + npm 双源同步发布；npx / git clone / Download ZIP / install.sh 四种安装方式，覆盖 17+ 类智能体目录 |
 | **便携记忆盘（随盘走）** | 记忆库即引擎：装在硬盘 / 主机上，插上即恢复全部记忆；引擎主机只需装 CLI 当存放点，无需装任何 AI 智能体 |
-| **局域网共享与自启** | 每智能体独立 token（Bearer + X-Agent-Id）鉴权、可吊销；`lan enable` 注册开机自启（Windows：优先计划任务，非管理员自动降级用户级 Startup 静默自启；Linux：systemd 用户单元，不可用时自动降级用户 crontab @reboot）；MCP 工具集与 CLI 一致（8 个工具），管理动作不远程暴露 |
+| **局域网共享与自启** | 每智能体独立 token（Bearer + X-Agent-Id + X-Agent-Key）鉴权、可吊销；`lan enable` 注册开机自启（Windows：优先计划任务，非管理员自动降级用户级 Startup 静默自启；Linux：systemd 用户单元，不可用时自动降级用户 crontab @reboot）；MCP 工具集与 CLI 一致（8 个工具），管理动作不远程暴露 |
 | **本地 / 局域网双模式** | 本地 `serve --stdio` 零进程、按需拉起（无常驻）；局域网 streamable HTTP 常驻——两种模式可并存、按需选用 |
 
 ## 功能详解
@@ -94,7 +101,7 @@
 - **物理隔离目录**：私密记忆按 owner 存放于 `private/<owner>/<type>/`，不同智能体的私密文件物理分离；旧版根下平铺的 `prefs/` `bounds/` `commits/` 在 `reindex` 时自动迁移。
 - **三种授权入口（满足任一即可读他人私密）**：
   1. `grants.json` 显式授权：`{"<userAgent>": ["<ownerAgent>", ...]}`；
-  2. identity=user：`--agent user` / `--owner user` / 环境变量 `YOTTA_AGENT_ID=user`；
+  2. identity=user：`--agent user` / `--owner user`，调用方仍需持有匹配的 agent_key；
   3. 显式 `--unsafe`（用户显式授权）。
 - **默认静默、显式跨读才报错**：默认 recall 遇其它 agent 私密静默跳过（不泄露「存在 N 条私密不可见」）；仅当显式跨智能体读取（`--all` / `--owner <其它>`）且无授权命中时才报错 / 警告。
 - **`--agent <其它>` 不越界**：`--agent <其它agent>` 仅作身份声明 / 展示用，不授予读取他人私密；读其它智能体私密仍需 grant / identity=user / `--unsafe`。
@@ -103,18 +110,18 @@
 
 ### 智能体身份（唯一 ID + 自我档案）
 
-每个智能体有一个**全局唯一的 agent ID**：它是私密记忆（PREF / BOUND / COMMIT）的归属键，也是远端接入的身份声明（`X-Agent-Id`）。
+每个智能体有一个**全局唯一的 agent ID**：它是私密记忆（PREF / BOUND / COMMIT）的归属键，也是远端接入的身份声明（`X-Agent-Id`）；远端加密私密读写还需匹配的 `X-Agent-Key`。
 
 - **登记（必须唯一）**：`yotta-memory iam <id>` 写入记忆库根目录 `agents.json`，**强制唯一性**——ID 已被其它主机 / 来源（含远端 token 登记）占用时拒绝，确认是同一智能体才 `--force`。
-- **确认身份**：`yotta-memory whoami`（远端 MCP 工具 `agent_info`）读「当次声明身份」（本机 `YOTTA_AGENT_ID` / CLI `--agent`；远端 `X-Agent-Id`），不猜不默认。
+- **确认身份**：`yotta-memory whoami --agent <id>`（远端 MCP 工具 `agent_info`）；身份不从环境变量读取。
 - **自我档案（强制落盘）**：`iam` 自动写一条 PREF `subject=自我接入档案`（owner=自己），statement 为 `; ` 分隔的 key:value：`agent_id / host / memory_home / mcp_mode（stdio|http）/ engine_url（仅远端）/ token（仅远端；本机不存 token）`。开工先 `recall "自我接入档案"` 找回身份与接入信息。
-- **本机免 token**：本机 CLI / stdio 直连不经网络、不校验 token；身份经该智能体 MCP 配置的 `env.YOTTA_AGENT_ID` 声明。本机多个智能体各自声明唯一 ID，互不撞。
+- **本机免网络 token**：本机 CLI / stdio 不校验 HTTP token，但私密访问仍必须 `agent_id + agent_key`；stdio MCP 用 `--agent-id` + `--agent-key-file` 显式传入，不再走身份 env。
 - **私密记忆必须有 owner**：写 PREF / BOUND / COMMIT 时未声明身份会被拒绝（公共 FACT 不受影响），从机制上防止「抄别人的 ID」。
 
-### 画像与开工上下文（v0.6.0 + v0.9.0）
+### 画像与开工上下文（v0.6.0 + v0.9.0 + v0.14.0）
 
 - **profile**：聚合 `private/<owner>/` 下 PREF / BOUND / COMMIT 原文，按 type + subject + tags 归组，写 `profile.md`；引擎零推断，画像结论由 AI 依据「记忆守则」内部形成，不当面贴标签。
-- **context**：一键生成开工上下文包——多智能体接入铁律 + 身份 + 用户画像摘要 + 任务相关记忆（`--focus`，v0.9.0）+ 近期记忆（按 importance 排序）+ 边界提醒 + 承诺 / 锚点；支持 `--budget` 字符预算与 `--explain` 选择解释。
+- **context**：一键生成开工上下文包——多智能体接入铁律 + 身份 + 长期理解摘要（`consolidate` 产物优先）+ 用户画像摘要 + 任务相关记忆（`--focus`）+ 近期走廊（按 updated / created 倒序）+ 近期高价值记忆（按 importance + utility 补位并去重）+ 边界提醒 + 承诺 / 锚点 + 会话闭环契约；支持 `--budget` 动态记忆字符预算与 `--explain` 选择解释。
 - **记忆守则**：SKILL.md 内置规则层（类型红线 / 主动捕获触发信号 / 了解用户三阶段四手法 / 心理学底座与对齐 / 底线与边界 / 宿主隔离 / 反模式），让 AI「越用越懂」有章法。
 
 ### 检索：语义检索（v0.8.0 + v0.9.0 embedding）
@@ -161,11 +168,12 @@
 |---|---|
 | 类型选错？ | 只提示不阻止；forget 后重写；--no-hint 关提示 |
 | 私密区加密？ | init 默认加密（主口令+恢复钥匙）；明文库 migrate 升级 |
-| 多智能体权限？ | FACT 公共；PREF/BOUND/COMMIT 按 owner 隔离，需 key authorize / view 授权 |
+| 多智能体权限？ | FACT 公共；PREF/BOUND/COMMIT 按 owner 隔离并绑定 agent_key，由用户通过 `view`（或 `key bind`）授权 |
 | 记忆找不到？ | config get 查位置 → reindex 重建索引 → recall/search |
 | 忘记主口令？ | 用恢复钥匙 reset-password（无私密区锁定的预期行为） |
 | 局域网怎么连？ | 引擎 lan enable + token new；客户端配 url+token |
 | MCP 没加载？ | 检查 mcpServers + 重启会话；本机直连用 CLI |
+| 版本不一致？ | 运行 `yotta-memory doctor --runtime`，按漂移项给出的修复命令升级并重启 |
 | 记忆库在哪？ | config get；项目级 .yottamemory |
 | 跨会话恢复？ | 开工跑 context + recall |
 | 备份迁移？ | export / import |
@@ -259,9 +267,12 @@ bash install.sh --list           # 列出智能体 -> 默认目录
 # 开工上下文包（yotta-memory context）
 ## 1. 身份
 ## 2. 用户画像摘要
-## 3. 近期记忆（按活跃度前 10 条）
-## 4. 边界提醒（BOUND）
-## 5. 承诺 / 锚点（COMMIT）
+## 2.5 长期理解摘要
+## 3. 近期走廊（按时间）
+## 4. 近期高价值记忆（补位）
+## 5. 边界提醒（BOUND）
+## 6. 承诺 / 锚点（COMMIT）
+## 7. 本会话闭环契约
 ```
 
 ## 升级
@@ -309,17 +320,17 @@ bash install.sh --agent <智能体名称>
 | `yotta-memory remember <type> <subject> <statement> [--owner <id>] [--source <来源>] [--weight <0..>] [--verify] [--no-hint]` | 写入记忆（同 subject+statement 自动更新；--owner 标注归属；--source 记录来源；--weight 重要性权重、去重取 max；--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`；`--agent <其它>` 仅作身份声明、不授予跨读；项目级优先）|
 | `yotta-memory profile [--owner <id>]` | 生成用户画像（聚合 `private/<owner>/` 原文，零推断，写 `profile.md`；跨 owner 默认拒绝）|
-| `yotta-memory context [--limit N] [--owner <id>] [--budget N] [--focus <关键词>] [--explain] [--embedding <命令>]` | 生成开工上下文包（身份 + 多智能体铁律 + 画像 + 任务相关记忆 + 近期记忆 + 边界 + 承诺；--budget 字符预算；--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]` | 开工可靠性检查（根目录 / 密钥库 / 索引 / 身份 / 最近备份；严重异常时锁定破坏性写入）|
+| `yotta-memory doctor [--json] [--runtime] [--mcp-config <文件>] [--skill-dir <目录>]` | 开工可靠性检查（根目录 / 密钥库 / 索引 / 身份 / 最近备份；严重异常时锁定破坏性写入；`--runtime` 检查 CLI / current / MCP 配置 / 运行中 server / 技能副本漂移）|
 | `yotta-memory archive [--days 180] [--threshold 0.4]` | 归档旧记忆（分类型衰减效用分 + 年龄；immutable / BOUND 豁免；私密入 `.archive/private/<owner>/<type>/`）|
 | `yotta-memory reindex` | 重建索引（手动改 .md 后校正）|
 | `yotta-memory export [--out f.json]` / `import <f.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（登记于记忆库 `.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]` | 启动 MCP 记忆引擎（streamable HTTP 局域网 / --stdio 本地零进程模式；Bearer token + X-Agent-Id + X-Agent-Key 鉴权）|
 | `yotta-memory lan enable [--onstart] / disable / status` | 开机自启管理（Windows：计划任务，默认 ONLOGON、--onstart 开机即启需管理员，非管理员自动降级用户级 Startup 静默自启；Linux：systemd 用户单元，不可用时自动降级用户 crontab @reboot）|
 | `yotta-memory maintain [--dry-run] [--apply] [--purge] [--threshold N] [--age N] [--dedup] [--dedup --apply] [--merge A,B]` | 记忆自组织：归档 / 遗忘候选 / 置信度查重 / 自动合并高置信组；默认 dry-run；`--dedup` 与归档互斥 |
 | `yotta-memory consolidate [--min-age N] [--min-idle N] [--max-utility N] [--min-group N] [--period N] [--type T] [--model <cmd>] [--apply] [--undo <batch>] [--batches]` | 周期摘要压缩（v0.10.0）：同主题旧记忆 → 带溯源摘要 + 原文归档；默认 dry-run；`--undo <batch>` 回滚批次；`--batches` 查批次 |
@@ -341,7 +352,9 @@ yotta-memory recall --type FACT --limit 10
 
 环境变量：
 - `YOTTA_MEMORY_HOME`：覆盖用户级记忆库目录（默认 `~/.yottamemory/`）。
-- `YOTTA_AGENT_ID` / `AGENT_ID`：当前 agent 标识（本机声明身份用，参与读取分区判定；私密记忆必须有 owner，未声明会被拒绝）。
+- `YOTTA_MEMORY_AGENT_HOME` / `YOTTA_MEMORY_AGENT_KEY_FILE`：`key status` / `key claim` 的显式 AI 宿主目录 / key 文件覆盖项；命令行 `--to` / `--agent-key-file` 优先级更高。
+
+身份环境变量（`YOTTA_AGENT_ID` / `AGENT_ID` / `YOTTA_MEMORY_AGENT_KEY` / `YOTTA_MEMORY_TRUST_ENV_AGENT`）已不支持：CLI 会忽略，HTTP / stdio MCP 启动时会直接拒绝，避免旧宿主配置静默沿用旧身份。
 
 ## 智能体接入后怎么用
 
@@ -352,20 +365,43 @@ yotta-memory recall --type FACT --limit 10
 记忆库可以装在任何主机或硬盘上（= 记忆引擎），供局域网内其它主机上的智能体远程接入：
 
 - **本机直连**：CLI 直接读写，无需 token；
-- **远程接入**：引擎主机运行 `yotta-memory serve` 常驻（或 `lan enable` 注册开机自启），远程智能体通过 MCP 以 `url + token` 连接。
-- **本地零进程**：本机 MCP 客户端可用 `serve --stdio` 按需拉起 CLI（无常驻进程）。
+- **远程接入**：引擎主机运行 `yotta-memory serve` 常驻（或 `lan enable` 注册开机自启），远程智能体通过 MCP 以 `url + token + agent_key` 连接；同机 / 共享文件系统用 `key claim` 领取，跨机不共享文件系统时由用户安全传输宿主 key 文件。
+- **本地零进程**：本机 MCP 客户端可用 `serve --stdio --agent-id <id> --agent-key-file <path>` 按需拉起 CLI（无常驻进程）。
+
+```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"
+      ]
+    }
+  }
+}
+```
 
 ### 引擎侧（记忆所在主机）
 
 1. 初始化或接入记忆库（见 CLI 用法）。
-2. 为需要访问的每个智能体生成独立 token：
+2. 安装或刷新稳定运行时入口：
+   ```bash
+   yotta-memory runtime install --from-current
+   yotta-memory runtime status
+   yotta-memory doctor --runtime
+   ```
+   > `lan enable` 与备份调度会自动做同样的 runtime 准备，只登记 `<runtimeRoot>/current/bin/yotta-memory.js`。
+3. 为需要访问的每个智能体生成独立 token：
    ```bash
    yotta-memory token new --agent <智能体ID>     # 打印一次，如 ytm_...（同 ID 已被其它来源占用需加 --force）
    yotta-memory token list                        # 查看已登记智能体
    yotta-memory token revoke --agent <智能体ID>   # 吊销
    ```
    > 新生成的 token 即时生效，无需重启服务。
-3. 启动服务（默认监听 0.0.0.0:8787，Bearer token + X-Agent-Id 鉴权）——临时运行或注册开机自启二选一：
+4. 启动服务（默认监听 0.0.0.0:8787，Bearer token + X-Agent-Id + X-Agent-Key 鉴权）——临时运行或注册开机自启二选一：
    ```bash
    yotta-memory serve                          # 临时前台运行
    yotta-memory lan enable                     # 注册开机自启（Windows：计划任务/用户级 Startup；Linux：systemd 用户单元/用户 crontab）
@@ -377,7 +413,14 @@ yotta-memory recall --type FACT --limit 10
 
 ### 客户端侧（远程智能体）
 
-在智能体 MCP 配置中登记连接（`url` + 两个请求头）：
+在智能体 MCP 配置中登记连接前，先确认该 AI 已领取 agent_key：
+
+```bash
+yotta-memory key status <智能体ID>
+yotta-memory key claim <智能体ID>
+```
+
+如果引擎与 AI 不在同一文件系统，`key claim` 不能在远端直接读取 pending，需要用户用密码管理器或安全文件传输把 key 放到目标宿主目录。然后再登记连接（`url` + 三个请求头）：
 
 ```json
 {
@@ -386,14 +429,15 @@ yotta-memory recall --type FACT --limit 10
       "url": "http://<引擎主机IP>:8787/mcp",
       "headers": {
         "Authorization": "Bearer <TOKEN>",
-        "X-Agent-Id": "<本智能体ID>"
+        "X-Agent-Id": "<本智能体ID>",
+        "X-Agent-Key": "<本智能体宿主 key 文件中的 agent_key>"
       }
     }
   }
 }
 ```
 
-连接后可通过 MCP tools（remember / recall / search / context / doctor / forget / archive / reindex / export / import / agent_info）读写记忆与确认身份；管理动作（init / config / token / lan / serve）不进 MCP，token 管理不远程暴露；MCP export/import 路径限记忆库内、distill 不支持 `--model`，MCP 也不接受远端传入 embedding 命令——embedding 插件只能由引擎主机本地 `config set embedding_cmd` 配置。`X-Agent-Id` 必须与 token 登记的智能体一致；读取分区规则与 CLI 相同（FACT 公共可读，PREF / BOUND / COMMIT 私密隔离）。
+连接后可通过 MCP tools（remember / recall / search / context / doctor / forget / archive / reindex / export / import / agent_info）读写记忆与确认身份；管理动作（init / config / token / lan / serve）不进 MCP，token 管理不远程暴露；MCP export/import 路径限记忆库内、distill 不支持 `--model`，MCP 也不接受远端传入 embedding 命令——embedding 插件只能由引擎主机本地 `config set embedding_cmd` 配置。`X-Agent-Id` 必须与 token 登记的智能体一致；加密私密读写还必须携带匹配的 `X-Agent-Key`。读取分区规则与 CLI 相同（FACT 公共可读，PREF / BOUND / COMMIT 私密隔离）。
 
 ### 位置持久化