@yottameta/yotta-memory 0.17.3 → 0.18.0

package/CHANGELOG.md

@@ -1,3 +1,58 @@
+## v0.18.0 (2026-09-26)
+
+第二波 P1：命中打点与容量水位 / consolidate 提案闸门 / 规模分级 / 上下文压缩审计。
+
+**命中打点与容量水位（A3）**
+
+- `recall` / `explain` / `feedback --useful` / `context` 记录本地命中元数据：`hit_days`（按天计数，默认保留 90 天，窗口可配）与 `hit_queries`（`sha256(query)` 前 8 位指纹计数，默认最多 12 槽，不保存查询原文）；字段随记忆文件一起加密 / 备份 / 导出。
+- 开关：`config set usage_enabled false` 全局关闭；`recall` / `explain` / `context` 支持 `--no-usage` 单次关闭。只读命令（`bench` / `doctor` / `scan` / `baseline` / `export` / `context --audit`）不写打点；跨 owner 私密条目不写（fail-closed）。
+- 新 `maintain --capacity [--json]`：只读报告水位（条目 / 记忆文件字节 / 索引字节 / 单目录最大文件数 / 冷启动）、30 / 90 天活跃度、LRU 与 LFU 淘汰候选、晋升建议（90 天命中 ≥ 3 且不同查询 ≥ 3，只打印建议命令）。淘汰候选排除冷却期（默认 30 天）与常青条目（immutable / BOUND / `evergreen` / `pinned`）。
+- `archive` 尊重冷却期与 `evergreen` / `pinned` 标签；`--force` 显式关闭这两项豁免（immutable 与 BOUND 始终豁免）。
+- 修复：加密库私密条目命中后，owner 加密索引在同一次调用内同步，不再滞等到 `reindex`。
+
+**consolidate 授权闸门（A5）**
+
+- `consolidate` 默认等价 `--propose`：输出结构化候选报告（候选统计 / 分组 / 摘要预览 / 归档目标 / 保留期 / 回滚命令），`--json` 供自动化读取；不写盘。
+- `--apply` 新增确认门：交互式需输入「X 组 / Y 条」确认串；非交互必须显式 `--yes`，否则拒绝退出（exit 2）。破坏性闸门（doctor + 独立备份 + 事务快照）与 `--undo <batch>` 回滚不变。
+- 首次启用时显示一次数据生命周期说明（保留期 + 检查 / 纠正 / 导出 / 停用 / 删除），按 `.archive` 审计记录判定，不新建标记文件；AI 不得代替用户执行 `--apply`。
+
+**规模与健康度分级（A6）**
+
+- `doctor` 规模体检新增四个 `scale_info_*` 阈值键与 `metrics[]` 逐项 `ok | info | warning`；文本增加健康度行（正常 / 提示 / 告警 + 最高项）。
+- `doctor.ok` 语义不变（只看 critical）：info / warning 都不锁定破坏性写入；`maintain --capacity` 复用同一套阈值与分级。
+
+**context --audit（A7）**
+
+- `context --audit [--from <文件|->] [--json] [--gate N]`：把被压缩掉的内容（宿主摘要或丢弃段落）喂进来，逐条核对是否已落盘；输出已落盘 / 未落盘 / 无法判定与 `remember` 建议命令；`--gate N` 在未落盘条数超过门槛时 exit 1。
+- 无 `--from` 时审计当前上下文包的 dropped 清单（duplicate / budget_exceeded），给出仍可召回的 `recall` 命令。全程只读：不复制输入、不自动补写、不写打点；只匹配当前身份可读条目。
+
+**MCP 只读 / 预演面**
+
+- MCP 工具面同步本批能力，但只补「只读 + 预演」子集：`archive` 新增 `dryRun`（只预览、零写入）；`maintain` 新增 `capacity`（只读容量水位报告）；`context` 新增 `audit` + `auditText` + `gate`（内联文本审计，**不接受文件路径**，也不读 stdin —— stdio MCP 的 fd 0 是协议流）；新增 `consolidate` 工具，只出 propose 报告。
+- 破坏性覆盖留在本机 CLI，MCP fail-closed：`archive --force` 不入 MCP（透传会被忽略）；`consolidate` 的 `--apply` / `--undo` / `--batches` 在 MCP 侧显式拒绝并提示改走 CLI（A5 闸门口径：AI 不得代替用户执行 `--apply`）。
+- 这样 MCP-first 宿主（只接 MCP 的客户端）也能用上容量水位 / 压缩审计 / 归档预演与压缩候选报告，同时不放开常青豁免与确认闸门。
+
+**修正（2026-09-26 验收回执）**
+
+- `archive --dry-run` 此前被静默吞掉（帮助声明「只预览归档结果」，`archiveCore` 却整段没读 `opts.dryRun`，照常移文件 + 建整库快照 + 写审计）。现在补齐预演分支：只打印将归档清单（文件 / 类型 / 天龄 / 效用 / subject）与跳过统计，**不动文件、不建事务快照、不写审计、不改索引**，输出以「预览（未改动）」开头；CLI 与 MCP（`dryRun`）共用同一条路径。
+- 顺带收口同批两处：`archive` 在没有候选时不再创建整库事务快照（无写入就不建快照）；`archive` 支持 `--json` 输出结构化报告（`mode / candidates / archived / skipped`，此前 `--json` 也被静默吞掉）；`archive` 被破坏性闸门拒绝时明确 exit 2。
+- `context --audit` 的 `remember` 建议命令 subject 改为在非标点边界截断（此前硬截 20 字符会切在「（」中间）。
+
+**测试**
+
+- 新增 `test/usage-hits.test.js` / `test/capacity-report.test.js` / `test/consolidate-propose.test.js` / `test/doctor-scale-levels.test.js` / `test/context-audit.test.js` / `test/archive-preview.test.js` / `test/mcp-v018-readonly-surface.test.js`；`npm test` 275 / 275 通过，帮助快照同步重算（`5bde7ffa…`）。
+
+## v0.17.4 (2026-09-26)
+
+新增 `rename`：给单条记忆改名，用来消除「平铺 / 分层同序号」冲突。
+
+- 用法：`yotta-memory rename <记忆 id> <新文件名> [--dry-run] [--reason <原因>] [--unsafe]`；新文件名需形如 `YYYY-MM-DD-NNNN.md`。
+- 身份键 = 类型 + owner + 文件名：目标名会**跨平铺 / 分层**检查同身份占用，占用即拒绝；目标文件已存在也拒绝覆盖（fail-closed）。
+- 写入闸门复用 `destructiveGuardCore`（doctor + 独立备份 + 事务快照）；改名后重建索引并写 `action: rename` 审计（含目标路径与原因）。
+- 权限：走 `checkOwnerWritable`，其它 owner 的私密记忆默认拒绝，需 `--unsafe` 显式授权。
+- `--dry-run` 只预览、零写入。命令仅 CLI 提供（写操作不进 MCP 工具面，工具数不变）。
+- 回归：新增 `test/rename.test.js` 5 项（冲突消除 + 跨布局占用拒绝 + 非法名 / 已存在拒绝 + owner 门 + dry-run 零写入）。
+
 ## v0.17.3 (2026-09-26)
 
 帮助可读性微调：顶层 `--help` 的每个选项去掉逐项重复的「做什么：」前缀，直接写说明正文；

package/README.md

@@ -23,6 +23,8 @@
 
 > 📖 The user-facing operations manual lives in [USER_GUIDE.md](USER_GUIDE.md).
 
+> 🆕 **v0.18.0 (hit tracking + capacity water level + consolidate gate + context audit)**: `recall` / `explain` / `feedback --useful` / `context` record local hit metadata (`hit_days`, retained 90 days by default; `hit_queries` stores only an 8-hex query fingerprint, up to 12 slots, never the query text) inside the memory file, so it travels with encryption / backup / export. Disable globally with `config set usage_enabled false` or per call with `--no-usage`; read-only commands and cross-owner private entries never write hits. New read-only `maintain --capacity [--json]` reports water level, 30/90-day activity, LRU/LFU eviction candidates (30-day cooldown; immutable / BOUND / `evergreen` / `pinned` exempt) and promotion suggestions (≥3 hits across ≥3 distinct queries; commands only, nothing is changed automatically). `archive` respects cooldown and evergreen tags, with `--force` to override those two exemptions. `consolidate` now defaults to `--propose` (structured report + `--json`); `--apply` requires an interactive confirmation token, or explicit `--yes` in non-interactive runs, and shows a one-time data-lifecycle notice. `doctor` scale checks gained `scale_info_*` thresholds and per-metric `ok / info / warning` levels (`doctor.ok` still only follows critical issues). New `context --audit [--from <file|->] [--json] [--gate N]` checks whether compressed-away content was persisted, printing missing items and `remember` suggestions without writing anything. `archive --dry-run` now truly previews (no file moves, no snapshot, no audit), a no-candidate run no longer takes a whole-store snapshot, and `archive --json` emits a structured report. On the MCP side this release adds read-only / preview inputs only (`archive.dryRun`, `maintain.capacity`, `context.audit` with inline `auditText`, and a propose-only `consolidate` tool), while `archive --force` and `consolidate --apply / --undo` stay CLI-only. Previous v0.17.4: `rename` removed flat/layered same-sequence collisions (cross-layout fail-closed, destructive guard, audit).
+> 🆕 **v0.17.4 (rename)**: `yotta-memory rename <id> <YYYY-MM-DD-NNNN.md>` renames a single memory entry — the minimal fix for flat/layered same-sequence collisions. Identity is type + owner + file name, checked across both layouts; an occupied target or an existing file is refused (fail-closed). Runs through the destructive guard (doctor + independent backup + snapshot), rebuilds the index and writes a `rename` audit entry; `--dry-run` previews with zero writes. CLI only — the MCP tool list is unchanged.
 > 🆕 **v0.17.3 (help readability)**: the top-level `--help` no longer repeats a "做什么：" label on every command and option — each entry starts straight with its description, while "什么时候用：" and "注意：" stay as-is. Help text only: commands, arguments and exit codes are unchanged.
 > 🆕 **v0.17.2 (owner gate for private maintenance)**: `explain` now refuses entries owned by another agent instead of printing their subject/statement, and `archive` / `maintain` skip private entries the caller does not own (declare your identity with `--agent <id>`; only an explicit user `--unsafe` overrides). Installer hardening: symlinked targets are refused and no whole-directory delete is performed. Previous v0.17.1: a mismatched identity-confirmation ID in `view` now shows an immediate error instead of returning silently; cancel stays silent and the server-side confirmation and destructive-operation gates are unchanged.
 > 🆕 **v0.17.0 (scale: year/month layout + doctor scale check + lazy index + bench)**: new entries are written into year/month folders — public `facts/<yyyy>/<mm>/`, private `private/<owner>/<type>/<yyyy>/<mm>/`. Flat files from v0.16 and earlier stay in place and remain readable; nothing is migrated automatically. Archiving keeps the year/month path, so same-named files from different months no longer overwrite each other. `doctor` gained a scale section (entry count / largest directory / index size / index cold start) with thresholds set through `config set scale_warn_entries` / `scale_warn_files_per_dir` / `scale_warn_index_bytes` / `scale_warn_cold_start_ms`; exceeding a threshold warns only and never locks destructive writes. Large stores can read only the shards of a given year: `recall --year <yyyy>` / `context --year <yyyy>` (repeatable; omitting it loads everything exactly as before). New `bench` command: deterministic auto sampling or `--evalset <file>` (evalset v1), reporting Recall@k / MRR / nDCG@k / HitRate with bootstrap 95% CI plus store and evalset fingerprints; `--gate <metric>=<value>` fits CI, and the same store + evalset + parameters always produce the same output. `bench` is read-only: it never rebuilds the index, never touches access counters and never calls an external embedding plugin. Previous v0.16.7: interactive `yotta-memory migrate --recovery-key-out` prompt, `YOTTA_MEMORY_PASS` for automation, and a `view` memory-home fingerprint before reusing a running server.
@@ -411,7 +413,7 @@ If the engine and the agent do not share a filesystem, `key claim` cannot read t
 }
 ```
 
-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).
+Once connected, MCP tools (remember / recall / search / context / doctor / forget / archive / reindex / export / import / agent_info / profile / feedback / maintain / distill / explain / consolidate) read/write memory and confirm identity; the `--tools core` profile keeps only `context / recall / search / remember`, and the full profile exposes 17 tools. 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

@@ -23,6 +23,8 @@
 
 > 📖 面向用户的操作手册见 [USER_GUIDE.md](USER_GUIDE.md)。
 
+> 🆕 **v0.18.0（命中打点 + 容量水位 + consolidate 提案闸门 + 上下文压缩审计）**：`recall` / `explain` / `feedback --useful` / `context` 记录本地命中元数据（`hit_days` 默认保留 90 天；`hit_queries` 只存查询 8 位指纹、最多 12 槽，不存原文；随文件加密 / 备份 / 导出），`config set usage_enabled false` 或命令级 `--no-usage` 可关；只读命令与跨 owner 私密条目不写。`maintain --capacity` 只读报告容量水位、30 / 90 天活跃度、LRU / LFU 淘汰候选（冷却期 30 天 + immutable / BOUND / evergreen / pinned 豁免）与晋升建议（≥3 次命中且 ≥3 个不同查询，只出建议命令）；`archive` 默认豁免冷却期与标签常青，`--force` 可显式覆盖。`consolidate` 默认等价 `--propose`（结构化报告 + `--json`），`--apply` 交互式需确认串、非交互必须 `--yes`；首次启用显示一次数据生命周期说明。`doctor` 规模体检新增 `scale_info_*` 与逐项 `ok / info / warning` 分级（`doctor.ok` 仍只看 critical）。新增 `context --audit [--from <文件|->] [--json] [--gate N]`：核对被压缩掉的内容是否已落盘，输出未落盘清单与 `remember` 建议命令，只读、不自动补写。`archive --dry-run` 只预览不改库（不动文件 / 不建事务快照 / 不写审计），无候选时不建整库快照，`archive --json` 输出结构化报告；MCP 侧只补只读 / 预演能力（`archive.dryRun`、`maintain.capacity`、`context.audit` + 内联 `auditText`、`consolidate` 只出 propose 报告），`archive --force` 与 `consolidate --apply / --undo` 仍只在命令行。上一版 v0.17.4：`rename` 消除平铺 / 分层同序号冲突（跨布局 fail-closed + 破坏性闸门 + 审计）。
+> 🆕 **v0.17.4（rename 改名）**：`yotta-memory rename <记忆 id> <YYYY-MM-DD-NNNN.md>` 给单条记忆改名，用于消除「平铺 / 分层同序号」冲突。身份键 = 类型 + owner + 文件名，跨两种布局检查；目标名被占用或文件已存在一律拒绝（fail-closed）。走破坏性闸门（doctor + 独立备份 + 事务快照），改名后重建索引并写 `rename` 审计；`--dry-run` 只预览零写入。仅 CLI 提供，MCP 工具面不变。
 > 🆕 **v0.17.3（帮助可读性）**：顶层 `--help` 不再逐项重复「做什么：」前缀——每条命令与选项直接写说明正文，「什么时候用：」与「注意：」保留不变。仅帮助文案变化，命令、参数与退出码零改动。
 > 🆕 **v0.17.2（私密维护的 owner 门）**：`explain` 对其它 owner 的私密条目改为直接拒绝，不再打印 subject / statement；`archive` / `maintain` 跳过不属于当前身份的私密条目（用 `--agent <id>` 声明身份，只有用户显式 `--unsafe` 才越界）。安装器加固：拒绝对符号链接目标写入，不做整目录删除。上一版 v0.17.1：`view` 删除 AI 身份时确认 ID 输入错误会立即提示「ID 不匹配，请输入完整 agent ID」，不再静默返回；用户取消仍保持静默，后端确认校验与破坏性操作闸门不变。
 > 🆕 **v0.17.0（规模：文件分层 + doctor 规模体检 + 索引按需加载 + bench 基准评测）**：新写入按年/月分层——公共 `facts/<年>/<月>/`、私密 `private/<owner>/<type>/<年>/<月>/`；v0.16 及更早的平铺文件留在原位继续可读，不做自动迁移。归档保留分层，不同月份的同名文件不会互相覆盖。`doctor` 新增规模段（记忆条数 / 单目录最大文件数 / 索引总体积 / 索引冷启动耗时），阈值用 `config set scale_warn_entries` / `scale_warn_files_per_dir` / `scale_warn_index_bytes` / `scale_warn_cold_start_ms` 调整，超阈值只告警，不锁定破坏性写入。大库检索可以按年份只读对应分片：`recall --year <yyyy>` / `context --year <yyyy>`（可重复传多次，不传即全量、行为与旧版一致）。新增 `bench` 可复算基准评测：默认按库内条目确定性抽样，`--evalset <文件>` 也可指定评测集；输出 Recall@k / MRR / nDCG@k / HitRate + 95% 置信区间、库指纹与评测集指纹，`--gate <指标>=<数值>` 可接 CI，同库同评测集同参数必得同结果；全程只读，不重建索引、不写访问计数、不调用外部 embedding。上一版 v0.16.7：明文库转加密推荐交互式 `yotta-memory migrate --recovery-key-out "$env:USERPROFILE\yotta-memory-recovery.key"`，自动化使用 `YOTTA_MEMORY_PASS`；`view` 复用端口前校验 memory_home 指纹。
@@ -83,9 +85,10 @@
 | **检索与生命周期** | 语义检索（v0.8.0：同义词 / 拼音 / 字段加权 / 模糊，零依赖）+ 效用分融合排序；统一效用分（盖棺分）规则层自动归档 / 遗忘候选 / 去重（`maintain`，默认 dry-run），记忆库越用越精简 |
 | **压缩遗忘（v0.10.0）** | `consolidate` 周期摘要压缩（旧记忆 → 带溯源摘要 + 原文归档，可回滚）+ 近重复自动合并（置信度 + `--apply`）+ 分类型衰减（FACT 730 / PREF 365 / COMMIT 90 天半衰，BOUND 不衰减）+ 批次审计（`--batches` / `--undo`），长期使用不膨胀、主题不丢 |
 | **越用越懂（v0.14.0）** | `context` 长期摘要优先 + `profile` 画像聚合（零推断）+ 近期走廊（按时间）+ 近期高价值补位 + 边界 / 承诺 + 会话闭环契约，记忆随使用成长 |
+| **容量水位与压缩审计（v0.18.0）** | 命中打点（查询只存指纹，可关）+ `maintain --capacity` 只读水位 / LRU·LFU 候选 / 晋升建议 + `consolidate` propose → `--apply --yes` 确认闸门 + `context --audit` 上下文压缩审计（未落盘决策清单）+ `archive --dry-run` 零写入预演；MCP 侧提供同一批能力的只读 / 预演子集 |
 | **生态分发** | 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 个工具），管理动作不远程暴露 |
+| **局域网共享与自启** | 每智能体独立 token（Bearer + X-Agent-Id + X-Agent-Key）鉴权、可吊销；`lan enable` 注册开机自启（Windows：优先计划任务，非管理员自动降级用户级 Startup 静默自启；Linux：systemd 用户单元，不可用时自动降级用户 crontab @reboot）；MCP 工具集按 core（4 个）/ full（17 个）分组暴露，管理动作（init / config / token / lan / serve）与破坏性覆盖（`archive --force`、`consolidate --apply / --undo`）不远程暴露 |
 | **本地 / 局域网双模式** | 本地 `serve --stdio` 零进程、按需拉起（无常驻）；局域网 streamable HTTP 常驻——两种模式可并存、按需选用 |
 
 ## 功能详解
@@ -330,23 +333,23 @@ bash install.sh --agent <智能体名称>
 |---|---|
 | `yotta-memory init [--project] [--dir <目录>]` | 初始化记忆库（默认用户级 `~/.yottamemory/`；--dir 显式指定位置）|
 | `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] [--year <yyyy>] [--agent <id>] [--owner <id>] [--all] [--unsafe] [--explain] [--semantic] [--embedding <命令>] [--embedding-timeout N]` | 检索记忆（语义+效用分排序；可选本地 embedding 插件；读取分区过滤；越界读其它智能体私密默认拒绝，需 grant / identity=user / `--unsafe`；`--agent <其它>` 仅作身份声明、不授予跨读；项目级优先；v0.17.0 起 `--year` 只读该年份分片，可重复传多次）|
+| `yotta-memory recall [关键词] [--type T] [--limit N] [--year <yyyy>] [--no-usage] [--agent <id>] [--owner <id>] [--all] [--unsafe] [--explain] [--semantic] [--embedding <命令>] [--embedding-timeout N]` | 检索记忆（语义+效用分排序；可选本地 embedding 插件；读取分区过滤；越界读其它智能体私密默认拒绝，需 grant / identity=user / `--unsafe`；`--agent <其它>` 仅作身份声明、不授予跨读；项目级优先；v0.17.0 起 `--year` 只读该年份分片，可重复传多次；`--no-usage` 单次关闭命中打点）|
 | `yotta-memory profile [--owner <id>]` | 生成用户画像（聚合 `private/<owner>/` 原文，零推断，写 `profile.md`；跨 owner 默认拒绝）|
-| `yotta-memory context [--limit N] [--owner <id>] [--budget N] [--focus <关键词>] [--year <yyyy>] [--explain] [--embedding <命令>]` | 生成开工上下文包（身份 + 铁律 + 画像 + 长期摘要 + 任务相关记忆 + 近期走廊 + 近期高价值 + 边界 + 承诺 + 会话闭环契约；--budget 控制动态记忆字符预算；--focus 任务聚焦；--year 限定年份；--explain 输出 included/dropped 选择解释）|
+| `yotta-memory context [--limit N] [--owner <id>] [--budget N] [--focus <关键词>] [--year <yyyy>] [--no-usage] [--explain] [--embedding <命令>]`；审计形态 `yotta-memory context --audit [--from <文件|->] [--json] [--gate N]` | 生成开工上下文包（身份 + 铁律 + 画像 + 长期摘要 + 任务相关记忆 + 近期走廊 + 近期高价值 + 边界 + 承诺 + 会话闭环契约；--budget 控制动态记忆字符预算；--focus 任务聚焦；--year 限定年份；--explain 输出 included/dropped 选择解释；--no-usage 单次关闭打点）。`--audit` 只读核对被压缩掉的内容是否已落盘，输出未落盘清单与 remember 建议；`--gate N` 在未落盘条数超过 N 时 exit 1；无 `--from` 时审计当前上下文包的 dropped 清单 |
 | `yotta-memory forget <文件>` | 删除一条记忆（按类型目录路径或文件名）|
 | `yotta-memory doctor [--json] [--runtime] [--mcp-config <文件>] [--skill-dir <目录>] [--baseline [--against <库路径>] [--template <文件>]]` | 开工可靠性检查（根目录 / 密钥库 / 索引 / 身份 / 最近备份；严重异常时锁定破坏性写入；`--runtime` 检查 CLI / current / MCP 配置 / 运行中 server / 技能副本漂移；`--baseline` 追加恢复 / 迁移六类只读探针，缺失项列出清单并 exit 2）|
 | `yotta-memory archive [--days 180] [--threshold 0.4]` | 归档旧记忆（分类型衰减效用分 + 年龄；immutable / BOUND 豁免；私密入 `.archive/private/<owner>/<type>/`）|
 | `yotta-memory reindex` | 重建索引（手动改 .md 后校正）|
 | `yotta-memory identity remove <id> [--dry-run] [--yes] [--keep-memories] [--keep-identity] [--password <口令> \| --recovery-key <钥匙>]` | 彻底删除一个 AI 身份与私密记忆（v0.17.0）：真删身份登记 / owner 密钥 / 授权绑定 / 待领取 key / 明文缓存 / `private/<id>/` 全部私密记忆 / token / grants 引用，并重建索引 + 写审计；**公共明文 FACT 保留**、其它 AI 零影响；只能由用户本人执行（加密库要主口令或恢复钥匙，明文库要显式 `--agent user`），`view` 的 AI 列表里也有「删除」按钮；破坏性闸门 = doctor + 独立备份 + 事务快照，`--dry-run` 只列清单 |
 | `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 config set <键> <值>` / `config get` | 记忆库位置与引擎参数（`memory_home` / `embedding_cmd` / `embedding_timeout` / `maintain_archived_utility` / `maintain_decay_halflife_<TYPE>` / `consolidate_*` / `usage_enabled` / `usage_retention_days` / `usage_query_slots` / `capacity_cooldown_days` / `capacity_warn_bytes` / `capacity_candidate_limit` / `promotion_min_hits` / `promotion_min_queries` / `scale_info_*` / `context_audit_min_coverage` 等）|
 | `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 鉴权）|
 | `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` 查批次 |
+| `yotta-memory maintain [--dry-run] [--apply] [--purge] [--threshold N] [--age N] [--dedup] [--dedup --apply] [--merge A,B]` / `maintain --capacity [--json]` | 记忆自组织：归档 / 遗忘候选 / 置信度查重 / 自动合并高置信组；默认 dry-run；`--dedup` 与归档互斥。`--capacity` 只读报告容量水位、LRU / LFU 淘汰候选与晋升建议（冷却期与常青条目豁免）|
+| `yotta-memory consolidate [--propose] [--min-age N] [--min-idle N] [--max-utility N] [--min-group N] [--period N] [--type T] [--model <cmd>] [--apply [--yes]] [--undo <batch>] [--batches]` | 周期摘要压缩：同主题旧记忆 → 带溯源摘要 + 原文归档；默认等价 `--propose`（结构化报告，不写盘）；`--apply` 需确认（非交互必须 `--yes`）；`--undo <batch>` 回滚批次；`--batches` 查批次 |
 | `yotta-memory feedback <文件|主题> --useful|--useless [--reason <原因>] [--undo]` | 使用反馈（useful/useless 调整 weight / confidence / feedback_net；`--undo` 回滚最近一次）|
 | `yotta-memory distill [--owner <id>] [--subject <主题>] [--model <cmd>] [--out <路径>]` | 心理日志蒸馏（统计摘要 / 主题画像 / 知识地图；可选本地模型，仅 CLI）|
 | `yotta-memory explain <文件|主题>` | 查看单条记忆效用分项与归档 / 遗忘 / BOUND 豁免状态 |

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: yotta-memory
-description: 元忆 —— 有权限边界的文件式智能体记忆。文件式、零依赖、可 diff/可回滚：让任何 AI 智能体活过会话，开工 recall 恢复上下文、重要信息 remember 落盘、收工归档。类型体系 FACT（公共共享）/ PREF / BOUND / COMMIT（私密隔离）。触发：记住、别忘了、记一笔、记忆、remember、recall、跨会话、上次说到、续测、交接、归档、记忆盘、共享记忆、局域网记忆、画像、开工上下文、长期理解摘要、近期走廊、会话闭环、记忆守则、profile、context、越用越懂、语义检索、反馈、维护、蒸馏、feedback、maintain、distill、explain、自我学习、自我进化、自我提升、查看平台分页、recall 候选预过滤、任务相关记忆、--focus、--embedding、压缩遗忘、consolidate、周期摘要、自动合并、分类型衰减、回滚、备份、backup、防误删、doctor、事务快照、基线探针、恢复演练、记忆库安全扫描、scan
-version: 0.17.3
+description: 元忆 —— 有权限边界的文件式智能体记忆。文件式、零依赖、可 diff/可回滚：让任何 AI 智能体活过会话，开工 recall 恢复上下文、重要信息 remember 落盘、收工归档。类型体系 FACT（公共共享）/ PREF / BOUND / COMMIT（私密隔离）。触发：记住、别忘了、记一笔、记忆、remember、recall、跨会话、上次说到、续测、交接、归档、记忆盘、共享记忆、局域网记忆、画像、开工上下文、长期理解摘要、近期走廊、会话闭环、记忆守则、profile、context、越用越懂、语义检索、反馈、维护、蒸馏、feedback、maintain、distill、explain、自我学习、自我进化、自我提升、查看平台分页、recall 候选预过滤、任务相关记忆、--focus、--embedding、压缩遗忘、consolidate、周期摘要、自动合并、分类型衰减、回滚、备份、backup、防误删、doctor、事务快照、基线探针、恢复演练、记忆库安全扫描、scan、命中打点、容量水位、--capacity、--propose、上下文压缩审计、context --audit
+version: 0.18.0
 license: MIT
 ---
 
@@ -28,6 +28,11 @@ license: MIT
 - **自我学习 / 自我进化 / 自我提升（v0.8.0）**：`recall` 语义检索（同义词 / 拼音 / 字段加权 / 模糊匹配，零依赖）；`feedback` 显式使用反馈闭环（useful / useless → weight / confidence / feedback_net 演化，越用越懂）；`maintain` 规则层自组织（统一效用分 + 年龄自动归档 / 遗忘候选 / 去重，默认 dry-run，immutable / BOUND 豁免）；`distill` 心理日志蒸馏（统计摘要 / 主题画像 / 知识地图，可选 `--model` 外部模型增强）；`explain` 查看单条记忆效用分项。
 - **召回质量与上下文选择（v0.9.0）**：`recall` 支持可选本地 embedding 插件（`--embedding <command>` / `config set embedding_cmd <command>`）；`context --focus <关键词>` 生成任务感知上下文；`--explain` 输出选择 trace，无插件时自动降级为词法检索。
 - **压缩遗忘（v0.10.0）**：记忆库长期可用不膨胀——`consolidate` 周期摘要压缩（把超龄 + 低效用 + 长期闲置的同主题旧记忆归纳成**带溯源**的摘要，原文整体进 `.archive/`，`--undo` 一键回滚）；`maintain --dedup` 近重复**自动合并**（置信度分档，`--apply` 批量执行高置信组）；效用分时效改为**分类型衰减**（FACT 慢 / PREF 中 / COMMIT 任务类快 / BOUND 不衰减）；`consolidate --batches` 批次审计可查。
+- **命中打点与容量水位（v0.18.0）**：`recall` / `explain` / `feedback --useful` / `context` 记录本地命中元数据（`hit_days` 稀疏日计数 + `hit_queries` 8 位查询指纹，不存查询原文；随文件加密 / 备份 / 导出）；`config set usage_enabled false` 或单命令 `--no-usage` 可关。`maintain --capacity` 只读报告容量水位、30 / 90 天活跃度、LRU / LFU 淘汰候选与晋升建议（只出建议命令，不自动动数据）；`archive` 默认豁免冷却期与 `evergreen` / `pinned` 条目，`--force` 可显式覆盖。开关与边界：只读命令（`bench` / `doctor` / `scan` / `context --audit` 等）不写打点；跨 owner 私密条目 fail-closed。
+- **consolidate 提案闸门（v0.18.0）**：`consolidate` 默认等价 `--propose`，输出结构化候选报告（分组 / 摘要预览 / 归档目标 / 保留期 / 回滚命令），`--json` 可读；`--apply` 需交互确认串，非交互必须显式 `--yes`。首次启用显示一次数据生命周期说明（检查 / 纠正 / 导出 / 停用 / 删除）。
+- **上下文压缩审计（v0.18.0）**：`context --audit [--from <文件|->] [--json] [--gate N]` 核对被压缩掉的内容里有没有还没落盘的决策，输出已落盘 / 未落盘 / 无法判定与 `remember` 建议命令；无 `--from` 时审计当前上下文包的 dropped 清单。只读，不自动补写。
+- **MCP 只读面（v0.18.0）**：本批能力在 MCP 侧只补「只读 + 预演」子集——`archive.dryRun`（预演）、`maintain.capacity`（容量水位）、`context.audit` + `auditText`（内联文本审计，不接受文件路径、不读 stdin）、`consolidate`（只出 propose 报告）。破坏性覆盖 `archive --force` 与 `consolidate --apply / --undo` 仍只在 CLI，由用户确认后执行；MCP 侧调用会被忽略或显式拒绝（fail-closed）。
+- **归档预演与 JSON（v0.18.0 修正）**：`archive --dry-run` 只打印将归档清单与跳过统计，不动文件、不建事务快照、不写审计；无候选时不建整库快照；`archive --json` 输出结构化报告（`mode / candidates / archived / skipped`）。
 - **可靠性基线（v0.12.0）**：`init` 对非空记忆库默认拒绝覆盖（`--attach` 接入现有库）；`forget` 先移入 `.trash/` 并写审计；新增 `backup volumes / setup / status / ensure-daily / schedule / drill`（用户确认真实独立卷后默认每日自动备份）与 `backup create / list / doctor / restore`。
 - **可靠性收口（v0.12.2）**：新增 `yotta-memory doctor` 开工检查（根目录 / 密钥库 / 索引 / 身份 / 最近备份）；`maintain --apply`、`consolidate --apply`、`merge`、`archive`、`--purge` 在写入前自动创建事务快照，快照失败或严重检查异常时拒绝写入。
 - **运行时 hook 声明（v0.13.0）**：manifest 声明 `after_milestone` / `remember_commit`；里程碑记忆必须有真实文件路径证据才标 verified，缺证据时输出 `explicit-unverified` + 一次纠偏。
@@ -50,7 +55,7 @@ AI 更新流程：先运行 `yotta-memory --version` 记录当前引擎版本；
 
 1. **开工定向**：先按「开工第一步：确认记忆位置 + 智能体身份」检测记忆库与身份，再运行 `yotta-memory context`（主注入：身份 + 长期理解摘要 + 用户画像 + 近期走廊 + 近期高价值 + 边界 + 承诺 + 会话闭环契约）恢复上下文，需要细节再 `yotta-memory recall <关键词>`；若有明确任务关键词，用 `context --focus <关键词>` 获得任务相关记忆；项目级记忆优先，其次用户级。
 2. **进行中落盘**：出现事实 / 偏好 / 边界 / 纠正 / 承诺信号时立即 `yotta-memory remember <type> <subject> <statement> --verify`，不攒到收工。
-3. **收工归档**：收工前复盘本轮，检查是否留下 COMMIT / 会话小结；有关键结论但未落盘时补写并 `recall` 回读，无长期价值不硬凑。旧记录定期 `yotta-memory maintain --apply`（单条低效用归档）+ 记忆多了周期 `yotta-memory consolidate --apply`（同主题压缩成带溯源摘要，`--undo` 可回滚）。
+3. **收工归档**：收工前复盘本轮，检查是否留下 COMMIT / 会话小结；有关键结论但未落盘时补写并 `recall` 回读，无长期价值不硬凑。旧记录定期 `yotta-memory maintain --apply`（单条低效用归档）+ 记忆多了先 `yotta-memory consolidate`（propose 报告）→ 确认后 `yotta-memory consolidate --apply --yes`（非交互；同主题压缩成带溯源摘要，`--undo` 可回滚）。上下文被宿主压缩过、担心有决策只留在对话里时，把压缩内容喂给 `yotta-memory context --audit --from <文件>` 核对。
 4. **多智能体纪律**：FACT 写入公共区，PREF / BOUND / COMMIT 只写本智能体私密区；不读取其他智能体私密区。**一切读写一律走 `yotta-memory` CLI / MCP 工具**——禁止用 shell（`Get-ChildItem` / `Get-Content` / `cat` / `ls` / `type` 等）直接读或改记忆库目录下的 `.md` / `index.json` / `tokens.json` / `agents.json` / `grants.json` 等文件，否则会绕过权限边界、读到别的智能体私密内容。
 
 ## 会话闭环契约（v0.14.0，AI 必做）
@@ -297,7 +302,7 @@ yotta-memory doctor --json
 | `yotta-memory backup volumes / setup --dir <目录> / status / ensure-daily / schedule enable|disable|status` | 每日自动备份（v0.12.0；只展示实际枚举的异卷、用户确认一次位置后默认每日执行，Windows Task Scheduler / systemd timer / launchd 调度，`serve` 补跑）|
 | `yotta-memory backup create / list / doctor / restore <ID> --to <目录> / drill [<ID>] [--probe] [--against <库路径>]` | 备份、恢复与恢复演练（v0.12.0；独立盘校验、SHA-256 清单、排除 `keys/cache`、恢复默认只写新目录；drill 验证 manifest / 索引 / 测试私密解密；v0.17.0 起 `--probe` 在恢复副本上追加六类基线探针，`--against` 校验备份没有落后于源库）|
 | `yotta-memory doctor [--json] [--runtime] [--mcp-config <文件>] [--skill-dir <目录>] [--baseline [--against <库路径>] [--template <文件>]]` | 开工可靠性检查（v0.12.2；根目录 / 密钥库 / 索引 / 身份 / 最近备份；严重异常时锁定破坏性写入）；全新空库的缺失 index / agents 降为 info；输出 agent home 发现规则与 `YOTTA_MEMORY_AGENT_HOME` 提示；加 `--runtime` 检查 CLI / current / MCP 配置 / 运行中 server / 技能副本漂移；v0.16.4 起 `--json` 含身份 / agent-key 状态；v0.16.5 起顶层含 `schemaVersion` / `encryption` / `migration_required`；v0.17.0 起 `checks.scale` 给规模体检（条数 / 单目录文件数 / 索引体积 / 冷启动耗时，阈值 `scale_*`），`--baseline` 追加恢复 / 迁移基线探针（结果进 `checks.baseline`，失败 exit 2）|
-| `yotta-memory archive [--days 180] [--threshold 0.35]` | 归档旧记忆（v0.8.0 统一效用分 + v0.10.0 分类型衰减；immutable / BOUND 豁免；私密归档入 `.archive/private/<owner>/<type>/`；阈值默认读 config `maintain_archived_utility`）|
+| `yotta-memory archive [--days 180] [--threshold 0.35] [--dry-run] [--force] [--json]` | 归档旧记忆（v0.8.0 统一效用分 + v0.10.0 分类型衰减；immutable / BOUND 豁免；v0.18.0 起默认豁免冷却期与 `evergreen` / `pinned`，`--force` 显式覆盖；私密归档入 `.archive/private/<owner>/<type>/`；阈值默认读 config `maintain_archived_utility`）。`--dry-run` 只预览、零写入（不动文件 / 不建快照 / 不写审计），无候选时不建整库快照，`--json` 输出结构化报告 |
 | `yotta-memory reindex` | 重建索引（手动改 .md 后校正）|
 | `yotta-memory export [--out f.json]` / `import <f.json>` | 导出 / 导入 |
 | `yotta-memory config set memory_home <目录>` / `config set backup_dir <目录>` / `config get [--json]` | 持久记住 / 查看记忆库位置与备份目录（`~/.yottamemory/config.json`；`get --json` 同时返回身份状态）；数值类键含 `maintain_*` / `consolidate_*` / `scale_*` / `backup_max_age_hours` |
@@ -565,7 +570,7 @@ MCP 模式由宿主显式声明身份：stdio 用 `--agent-id <agent_id> --agent
 4. 按当前智能体机制重载 MCP（必要时请用户重启会话）；
 5. 用 MCP tools 读写记忆。
 
-> MCP 工具集与 CLI 一致：remember / recall / search / forget / archive / reindex / export / import / profile；管理动作（init / config / token / lan / serve）不进 MCP，token 管理不远程暴露；MCP export/import 路径限记忆库内、distill 不支持 `--model`（仅本地 CLI）。
+> MCP 工具集（full 17 个）：remember / recall / search / context / doctor / forget / archive / reindex / export / import / agent_info / profile / feedback / maintain / distill / explain / consolidate；管理动作（init / config / token / lan / serve）不进 MCP，token 管理不远程暴露；MCP export/import 路径限记忆库内、distill 不支持 `--model`（仅本地 CLI）。v0.18.0 起 MCP 只补只读 / 预演能力（`archive.dryRun`、`maintain.capacity`、`context.audit` + 内联 `auditText`、`consolidate` 只出 propose）；破坏性覆盖（`archive --force`、`consolidate --apply / --undo`）只在 CLI，MCP 侧忽略或拒绝。
 
 > 工具分组（v0.15.0）：常驻场景用 `yotta-memory serve --stdio --tools core --agent-id <id> --agent-key-file <path>`，只暴露 `context / recall / search / remember`；需要诊断、维护、导入导出时用 `--tools full`。调用不属于当前分组的工具会返回明确提示，不会静默执行。
 

package/USER_GUIDE.md

@@ -35,7 +35,7 @@
 - **越用越懂（v0.14.0）**：AI 按「记忆守则」主动捕获信号，`context` 开工注入长期摘要、画像、近期走廊、边界、承诺与会话闭环契约——用得越久越懂你。
 - **自我学习 / 自我进化 / 自我提升（v0.8.0 + v0.9.0）**：`recall` 语义检索（同义词 / 拼音 / 字段加权 / 模糊，v0.9.0 可选本地 embedding 插件）+ `feedback` 使用反馈闭环 + `maintain` 规则层自组织 + `distill` 心理日志蒸馏——记忆系统会自己整理、提炼、演化。
 - **可靠性基线（v0.12.0 / v0.12.2）**：`init` 对已有库拒绝覆盖；`forget` 进回收区；`backup volumes/setup/status/ensure-daily/schedule/drill` 在用户确认真实独立卷后默认每日自动备份，并提供校验、恢复与恢复演练；`doctor` 开工检查风险，破坏性操作写入前自动创建事务快照。
-- **MCP 工具分组（v0.15.0）**：`serve --tools core` 只暴露 `context / recall / search / remember`，适合常驻；`--tools full` 提供完整诊断与维护工具。未指定时默认 `full`。
+- **MCP 工具分组（v0.15.0）**：`serve --tools core` 只暴露 `context / recall / search / remember`，适合常驻；`--tools full` 提供完整诊断与维护工具。未指定时默认 `full`。v0.18.0 起 MCP 追加只读 / 预演能力（`archive.dryRun`、`maintain.capacity`、`context.audit` + 内联 `auditText`、`consolidate` 只出 propose 报告）；`archive --force` 与 `consolidate --apply / --undo` 只在命令行，MCP 调用会被忽略或拒绝。
 
 ## 2. 安装（CLI + 技能）
 
@@ -95,6 +95,7 @@ yotta-memory iam <id> --name 元忆 --user 用户 --relationship 伙伴   # 自
 
 - `profile` 引擎零推断：只按类型 / 主题 / 标签归组呈现原文，画像结论由 AI 内部形成，不当面贴标签。
 - `context` 是每次会话开工的主注入，替代裸 `recall`；长期摘要优先、近期走廊按时间取样、近期高价值补位按文件去重；无画像时自动生成一次或降级，不报错；`--budget` 控制动态记忆字符预算，长期摘要 / 身份 / 铁律 / 画像 / 边界 / 承诺 / 闭环契约必保（token 恒定）。
+- `context --audit [--from <文件|->] [--json] [--gate N]`：把宿主压缩后的摘要或丢弃段落喂给元忆，逐条核对是否已落盘；输出已落盘 / 未落盘 / 无法判定与 `remember` 建议命令（只打印、不执行）。`--gate N` 在未落盘条数超过 N 时 exit 1，可接自动化。不传 `--from` 时审计当前上下文包的 dropped 清单。审计全程只读：不复制输入、不自动补写、不写命中打点。
 - `remember --verify` 写后回读校验；`remember --no-hint` 关闭「疑似偏好，建议 PREF」的提示。
 
 ### 记忆库位置：本机智能体如何找到记忆
@@ -218,8 +219,15 @@ yotta-memory recall <关键词> --agent <id> --agent-key-file "<AI_HOME>/.yotta-
 - `maintain --dedup`：查重复候选并给**置信度分档**——≥0.85 高置信（可自动合并）/ 0.65–0.85 建议手动 / 其余忽略。
 - `maintain --dedup --apply`：自动合并同归属（同类型 + 同 scope/owner）高置信组：保留 confidence 最高的一条，合并 tags / 使用次数 / 反馈，其余移入 `.archive/` 并写批次审计（可 `consolidate --undo <batch>` 回滚）。**注意 `--dedup` 与归档互斥**：`--dedup [--apply]` 只查重 / 自动合并，不会顺手归档单条旧记忆——要归档请单独跑 `maintain --apply`。
 - `maintain --merge A,B`：手动合并两条相似记忆（保留高 confidence，低 confidence 归档）。
+- `maintain --capacity [--json]`：只读容量报告——水位（条目 / 文件字节 / 索引 / 单目录 / 冷启动）、30 / 90 天活跃度、LRU 与 LFU 淘汰候选、晋升建议（≥3 次命中且 ≥3 个不同查询）。候选排除 30 天冷却期与常青条目（immutable / BOUND / `evergreen` / `pinned`）；每条候选 / 建议都带可执行命令，报告本身不改任何文件。
 - 阈值与半衰可用 `config set maintain_archived_utility 0.3` / `config set maintain_decay_halflife_FACT 1000` 等调整（`config get` 查看）；审计在 `.archive/audit-<日期>.jsonl`。
 
+**归档（archive）**
+
+- `archive [--days 180] [--threshold 0.35] [--dry-run] [--json]`：把「效用低于阈值且超过 N 天没用」的旧记忆移入 `.archive/`（可恢复）。`--dry-run` 只打印将归档清单（文件 / 类型 / 天龄 / 效用 / subject）与跳过统计，**不动文件、不建事务快照、不写审计**。
+- 默认豁免：冷却期（`config set capacity_cooldown_days`，默认 30 天）与常青条目（immutable / BOUND / `evergreen` / `pinned`）。`--force` 只覆盖冷却期与标签常青，immutable 与 BOUND 始终豁免。
+- 真正执行前先过破坏性写入闸门（doctor + 独立备份 + 异卷）并创建事务快照；没有候选时不会建快照。`--json` 输出结构化报告（`mode / candidates / archived / skipped`），便于自动化读取。
+
 **分类型衰减曲线（v0.10.0）**
 
 - 记忆「价值」由效用分衡量，其中「时效」分量按类型指数衰减：`时效 = 0.5^(已过天数 / 半衰期)`。
@@ -231,7 +239,8 @@ yotta-memory recall <关键词> --agent <id> --agent-key-file "<AI_HOME>/.yotta-
 
 - 干什么：记忆库长期使用后，同一主题会积累大量「又老又不常用」的旧条目。`consolidate` 把这类旧记忆归纳成 **1 条带溯源的周期摘要**（留在活跃区，recall 能搜到），原文整体进 `.archive/`——主题叙事不丢、记忆库不膨胀。
 - 候选条件（全部满足才收）：created 距今 ≥ 180 天（`--min-age`）∧ 长期闲置 ≥ 90 天（`--min-idle`，最近用过的不收）∧ 效用 ≤ 0.6（`--max-utility`，重要的不收）；同主题 ≥ 2 条成组（`--min-group`）。**immutable / BOUND 永远豁免**。
-- 用法：先 `yotta-memory consolidate` 看预览（列出每组摘要计划与影响条数），确认后 `yotta-memory consolidate --apply` 执行。
+- 用法：先 `yotta-memory consolidate`（默认等价 `--propose`）看结构化报告——每组主题 / 条数 / 天龄区间 / 平均效用 / 摘要预览 / 原文归档目标，以及保留期与回滚命令；确认后 `yotta-memory consolidate --apply` 执行（交互式需输入「X 组 / Y 条」确认串；脚本等非交互环境必须显式加 `--yes`）。首次执行会显示一次数据生命周期说明（检查 / 纠正 / 导出 / 停用 / 删除）。也可以用 `--json` 让自动化读取候选报告。
+- 保留期与回滚：原文移入 `.archive/` 后一直保留，直到你显式 `maintain --purge` 或 `consolidate --undo <batch>`；`--apply` 前的 doctor + 独立备份 + 事务快照闸门不变。
 - 摘要形态：新记忆 `subject = 周期摘要 <主题>（<N>天窗）`、tags 含 `consolidate` / `summary`、正文含主题要点 + **溯源清单**（每条原文路径 / 日期 / confidence），statement 简短可检索。
 - 归属：公共 FACT 摘要进 `facts/`；私密 PREF / COMMIT 摘要进 `private/<owner>/<type>/`（密文库自动加密）。
 - 可选模型提炼：`consolidate --apply --model <命令>`（仅本机 CLI，stdin→stdout 协议同 distill；失败自动降级启发式）。
@@ -442,7 +451,7 @@ yotta-memory key claim <本智能体ID>
 | `yotta-memory context [--limit N] [--owner <id>] [--budget N] [--focus <关键词>] [--year <yyyy>] [--explain] [--embedding <命令>]` | 开工上下文包（身份+铁律+画像+长期摘要+任务相关记忆+近期走廊+近期高价值+边界+承诺+会话闭环契约；--budget 控制动态记忆字符预算；--focus 任务聚焦；v0.17.0 起 `--year` 只装载指定年份；--explain 输出 included/dropped 选择解释）|
 | `yotta-memory forget <文件>` | 删除一条记忆 |
 | `yotta-memory doctor [--json] [--runtime] [--mcp-config <文件>] [--skill-dir <目录>] [--baseline [--against <库路径>] [--template <文件>]]` | 开工可靠性检查（v0.12.2：根目录 / 密钥库 / 索引 / 身份 / 最近备份；严重异常时锁定破坏性写入；v0.16.0：`--runtime` 检查 CLI / current / MCP 配置 / 运行中 server / 技能副本漂移；v0.17.0：`checks.scale` 规模体检 + `--baseline` 恢复 / 迁移六类只读探针，失败列出缺失清单并 exit 2）|
-| `yotta-memory archive [--days 180] [--threshold 0.4]` | 归档旧记忆（分类型衰减效用分 + 年龄；immutable / BOUND 豁免；保留年/月分层，私密入 `.archive/private/<owner>/<type>/<年>/<月>/`）|
+| `yotta-memory archive [--days 180] [--threshold 0.4] [--dry-run] [--force] [--json]` | 归档旧记忆（分类型衰减效用分 + 年龄；immutable / BOUND 豁免，默认豁免冷却期与 `evergreen` / `pinned`、`--force` 覆盖；保留年/月分层，私密入 `.archive/private/<owner>/<type>/<年>/<月>/`）；`--dry-run` 零写入预览 |
 | `yotta-memory reindex` | 重建索引 |
 | `yotta-memory identity remove <id> [--dry-run] [--yes] [--keep-memories] [--keep-identity] [--password <口令> | --recovery-key <钥匙>]` | 彻底删除一个 AI 身份与私密记忆（v0.17.0：真删身份登记 / owner 密钥 / 授权绑定 / 待领取 key / 缓存 / `private/<id>/` / token / grants 并重建索引 + 写审计；公共明文 FACT 保留、其它 AI 零影响；只能由用户本人执行，`view` 里也有「删除」按钮；破坏性闸门 = doctor + 独立备份 + 事务快照）|
 | `yotta-memory export [--out 文件.json]` / `import <文件.json>` | 导出 / 导入 |
@@ -454,8 +463,8 @@ yotta-memory key claim <本智能体ID>
 | `yotta-memory runtime list / install <tarball|版本> [--from-current] [--force] / use <版本> [--restart] / rollback [--restart] / status` | 运行时稳定入口（runtime.json + versions + current；安装 / 切换 / 回滚 / 查看漂移；`--restart` 尝试重启受管 server）|
 | `yotta-memory lan enable [--onstart] / disable / status` | 开机自启管理（Windows：计划任务/用户级 Startup 静默自启；Linux：systemd 用户单元/用户 crontab @reboot）|
 | `yotta-memory feedback <文件|主题> --useful|--useless [--reason <原因>] [--undo]` | 使用反馈（v0.8.0：useful/useless 调 weight/confidence/feedback_net；--undo 回滚）|
-| `yotta-memory maintain [--dry-run] [--apply] [--purge] [--threshold N] [--age N] [--dedup] [--dedup --apply] [--merge A,B]` | 记忆自组织（v0.8.0 + v0.10.0 自动合并）：归档 / 遗忘候选 / 置信度查重 / 自动合并；默认 dry-run，`--dedup` 与归档互斥 |
-| `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` 查批次）|
+| `yotta-memory maintain [--dry-run] [--apply] [--purge] [--threshold N] [--age N] [--dedup] [--dedup --apply] [--merge A,B] [--capacity [--json]]` | 记忆自组织（v0.8.0 + v0.10.0 自动合并 + v0.18.0 容量水位）：归档 / 遗忘候选 / 置信度查重 / 自动合并；默认 dry-run，`--dedup` 与归档互斥；`--capacity` 只读报告水位、LRU / LFU 候选与晋升建议 |
+| `yotta-memory consolidate [--min-age N] [--min-idle N] [--max-utility N] [--min-group N] [--period N] [--type T] [--model <cmd>] [--apply] [--yes] [--undo <batch>] [--batches]` | 周期摘要压缩（v0.10.0 起：同主题旧记忆 → 带溯源摘要 + 原文归档；v0.18.0 起默认等价 `--propose` 只出报告，`--apply` 非交互必须 `--yes`，`--undo <batch>` 回滚批次，`--batches` 查批次）|
 | `yotta-memory distill [--owner <id>] [--subject <主题>] [--model <cmd>] [--out <路径>]` | 心理日志蒸馏（v0.8.0：统计摘要 / 主题画像 / 知识地图）|
 | `yotta-memory explain <文件|主题>` | 查看单条记忆效用分项（v0.8.0）|
 | `yotta-memory bench [--evalset <文件>] [--k N] [--seed N] [--bootstrap N] [--ablate] [--gate <指标>=<数值>] [--timing] [--year <yyyy>] [--json] [--out <文件>]` | 可复算检索基准评测（v0.17.0：默认按库内条目确定性抽样；`--evalset` 指定评测集 v1；指标 Recall@k / MRR / nDCG@k / HitRate + 95% 置信区间；报告含库指纹、默认不含墙钟时间；`--ablate` 消融对比；`--gate` 供 CI；`--timing` 附带耗时后不可逐字节复算；全程只读）|