@yottameta/yotta-memory 0.13.2 → 0.16.1

package/CHANGELOG.md

@@ -1,3 +1,50 @@
+## v0.16.1 (2026-09-19)
+
+维护性重发（无功能变更）：
+
+- 发布包清理：平台分发副本不再包含误打包的历史 tarball（构建脚本已排除 `*.tgz` 等压缩包并新增归档校验）。
+- 检索文案更新：分发副本的 summary / description 使用连写关键词（AI记忆系统 / 长期记忆 / 永久记忆 / 记忆引擎），并为该成果增加构建守卫。
+
+## 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 绑定**

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,7 +23,12 @@
 
 > 📖 The user-facing operations manual lives in [USER_GUIDE.md](USER_GUIDE.md).
 
-> 🆕 **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> --to <AI_HOME>` / `key claim <id> --to <AI_HOME>` 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.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.
 
@@ -44,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.
@@ -83,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 network token locally**: local CLI / stdio bypasses HTTP tokens, but private access still requires `agent_id + agent_key`; MCP declares the key through per-process `YOTTA_MEMORY_AGENT_KEY` and `YOTTA_MEMORY_TRUST_ENV_AGENT=1`.
+- **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)
@@ -129,6 +134,7 @@ Each agent has a globally unique agent ID: it is the ownership key for private m
 | 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 |
@@ -222,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
@@ -270,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 |
@@ -302,8 +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`: per-process MCP identity only; trusted only with `YOTTA_MEMORY_TRUST_ENV_AGENT=1`, never as a user-level global fallback.
-- `YOTTA_MEMORY_AGENT_KEY`: per-agent 32-byte key used to unwrap `keys/bindings/<id>.key.agent`; required for encrypted private reads/writes. After authorization, the AI runs `key status` / `key claim` to store it at `<AI_HOME>/.yotta-memory-agent-key`, and the MCP host injects it from that file.
+- `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
 
@@ -315,19 +325,42 @@ The store can live on any host or disk (= the memory engine) and be reached by a
 
 - **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 + 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` to launch the CLI on demand (no resident process).
+- **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 + X-Agent-Key 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)
@@ -342,8 +375,8 @@ The store can live on any host or disk (= the memory engine) and be reached by a
 Before registering the connection, confirm the agent has claimed its key:
 
 ```bash
-yotta-memory key status <agent-id> --to <AI_HOME>
-yotta-memory key claim <agent-id> --to <AI_HOME>
+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):

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,7 +23,12 @@
 
 > 📖 面向用户的操作手册见 [USER_GUIDE.md](USER_GUIDE.md)。
 
-> 🆕 **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> --to <AI_HOME>` / `key claim <id> --to <AI_HOME>` 领取到 `<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.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` 在写入前自动创建事务快照，快照失败或严重异常时拒绝写入。
 
@@ -48,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` 检查根目录 / 密钥库 / 索引 / 身份 / 最近备份，破坏性操作在写入前自动创建事务快照。
@@ -67,7 +72,7 @@
 | **双级存储** | 用户级 `~/.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 + X-Agent-Key）鉴权、可吊销；`lan enable` 注册开机自启（Windows：优先计划任务，非管理员自动降级用户级 Startup 静默自启；Linux：systemd 用户单元，不可用时自动降级用户 crontab @reboot）；MCP 工具集与 CLI 一致（8 个工具），管理动作不远程暴露 |
@@ -108,15 +113,15 @@
 每个智能体有一个**全局唯一的 agent ID**：它是私密记忆（PREF / BOUND / COMMIT）的归属键，也是远端接入的身份声明（`X-Agent-Id`）；远端加密私密读写还需匹配的 `X-Agent-Key`。
 
 - **登记（必须唯一）**：`yotta-memory iam <id>` 写入记忆库根目录 `agents.json`，**强制唯一性**——ID 已被其它主机 / 来源（含远端 token 登记）占用时拒绝，确认是同一智能体才 `--force`。
-- **确认身份**：`yotta-memory whoami --agent <id>`（远端 MCP 工具 `agent_info`）；环境身份只在 MCP 信任标记下有效，不再接受用户级全局 `YOTTA_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 不校验 HTTP token，但私密访问仍必须 `agent_id + agent_key`；MCP 通过独立进程 env 注入。
+- **本机免网络 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）
@@ -168,6 +173,7 @@
 | 忘记主口令？ | 用恢复钥匙 reset-password（无私密区锁定的预期行为） |
 | 局域网怎么连？ | 引擎 lan enable + token new；客户端配 url+token |
 | MCP 没加载？ | 检查 mcpServers + 重启会话；本机直连用 CLI |
+| 版本不一致？ | 运行 `yotta-memory doctor --runtime`，按漂移项给出的修复命令升级并重启 |
 | 记忆库在哪？ | config get；项目级 .yottamemory |
 | 跨会话恢复？ | 开工跑 context + recall |
 | 备份迁移？ | export / import |
@@ -261,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. 本会话闭环契约
 ```
 
 ## 升级
@@ -311,14 +320,14 @@ 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 --agent <id>` | 查看当前显式身份与登记状态；环境身份仅在 MCP 信任标记下有效 |
+| `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 + X-Agent-Key 鉴权）|
@@ -343,8 +352,9 @@ yotta-memory recall --type FACT --limit 10
 
 环境变量：
 - `YOTTA_MEMORY_HOME`：覆盖用户级记忆库目录（默认 `~/.yottamemory/`）。
-- `YOTTA_AGENT_ID` / `AGENT_ID`：仅用于 MCP 进程身份，必须配合 `YOTTA_MEMORY_TRUST_ENV_AGENT=1`；禁止用户级全局 fallback。
-- `YOTTA_MEMORY_AGENT_KEY`：per-agent 32 字节 key，用于解开 `keys/bindings/<id>.key.agent`；加密私密读写必填。授权后先由 AI 执行 `key status` / `key claim` 领取到 `<AI_HOME>/.yotta-memory-agent-key`，MCP 宿主再从该文件注入。
+- `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 启动时会直接拒绝，避免旧宿主配置静默沿用旧身份。
 
 ## 智能体接入后怎么用
 
@@ -356,19 +366,42 @@ yotta-memory recall --type FACT --limit 10
 
 - **本机直连**：CLI 直接读写，无需 token；
 - **远程接入**：引擎主机运行 `yotta-memory serve` 常驻（或 `lan enable` 注册开机自启），远程智能体通过 MCP 以 `url + token + agent_key` 连接；同机 / 共享文件系统用 `key claim` 领取，跨机不共享文件系统时由用户安全传输宿主 key 文件。
-- **本地零进程**：本机 MCP 客户端可用 `serve --stdio` 按需拉起 CLI（无常驻进程）。
+- **本地零进程**：本机 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 + X-Agent-Key 鉴权）——临时运行或注册开机自启二选一：
+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）
@@ -383,8 +416,8 @@ yotta-memory recall --type FACT --limit 10
 在智能体 MCP 配置中登记连接前，先确认该 AI 已领取 agent_key：
 
 ```bash
-yotta-memory key status <智能体ID> --to <AI_HOME>
-yotta-memory key claim <智能体ID> --to <AI_HOME>
+yotta-memory key status <智能体ID>
+yotta-memory key claim <智能体ID>
 ```
 
 如果引擎与 AI 不在同一文件系统，`key claim` 不能在远端直接读取 pending，需要用户用密码管理器或安全文件传输把 key 放到目标宿主目录。然后再登记连接（`url` + 三个请求头）：