@yottameta/yotta-memory 0.17.3 → 0.18.0

package/package.json

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

package/references/faq.md

@@ -98,3 +98,12 @@ yotta-memory recall <关键词> --agent <id> --agent-key-file "<AI_HOME>/.yotta-
 
 ## 18. 怎么证明改了检索 / 索引之后「没变差」？
 用 `yotta-memory bench`。默认按库内条目做确定性抽样生成基线评测集，也可以用 `--evalset <文件>` 固定一组查询（评测集 v1：`{"version":1,"queries":[{"query":"...","expect":["<记忆 id>"]}]}`，记忆 id 写相对路径或文件名都可以）。报告给 Recall@k / MRR / nDCG@k / HitRate + 固定种子 bootstrap 95% 置信区间，并写明库指纹与评测集指纹——同库、同评测集、同参数必须同输出，所以改前跑一次、改后再跑一次就能直接对比。接 CI 用 `--gate mrr=0.6`（不达标 exit 1）；`--ablate` 对比关键词 / 语义 × 融合 / 纯分四组；想要耗时再加 `--timing`（带上后报告标记为不可逐字节复算）。`bench` 全程只读：不重建索引、不写访问计数、不调用外部 embedding 插件；索引缺失或版本过旧时会提示先 `reindex`。
+
+## 19. 命中打点记录了什么？会不会泄露我的查询？
+每条被命中的记忆会在自己的 frontmatter 里记录 `hit_days`（按天 + 信号类型 `s` / `g` / `u` 计数，默认只保留最近 90 天）与 `hit_queries`（只存 `sha256(查询)` 前 8 位指纹 + 次数，默认最多 12 槽，**不保存查询原文**）。字段随记忆文件一起加密 / 备份 / 导出，不外传、不联网。全局关闭：`yotta-memory config set usage_enabled false`；单次关闭：`recall` / `explain` / `context` 加 `--no-usage`。`bench` / `doctor` / `scan` / `baseline` / `export` / `context --audit` 不写打点；跨 owner 私密条目不写（fail-closed）。保留窗口与槽位用 `usage_retention_days` / `usage_query_slots` 调整。
+
+## 20. 怎么知道记忆库该清理哪些条目？
+先跑 `yotta-memory maintain --capacity`（加 `--json` 供自动化读取）。它是只读报告：水位（条目 / 文件字节 / 索引 / 单目录 / 冷启动）、30 / 90 天活跃度、LRU（最久未用）与 LFU（命中最少）淘汰候选、晋升建议（90 天命中 ≥ 3 且不同查询 ≥ 3）。候选会排除 30 天冷却期与常青条目（immutable / BOUND / `evergreen` / `pinned`），并且只给可执行命令，不自动归档或改权重。阈值用 `capacity_warn_bytes` / `capacity_cooldown_days` / `capacity_candidate_limit` / `promotion_min_hits` / `promotion_min_queries` 调整；`doctor` 的规模分级用 `scale_info_*` / `scale_warn_*` 调整。
+
+## 21. consolidate --apply 为什么必须加 --yes？上下文压缩后怎么核对没丢决策？
+`consolidate --apply` 会移动原文并生成摘要，属于破坏性写入：交互式执行需要输入「X 组 / Y 条」确认串，脚本等非交互环境必须显式 `--yes`，否则拒绝执行（exit 2）。先跑 `yotta-memory consolidate`（等价 `--propose`）看结构化报告与回滚命令；原文一直保留在 `.archive/`，可 `consolidate --undo <batch>` 回滚。如果担心上下文被宿主压缩后丢了决策，用 `yotta-memory context --audit --from <压缩内容文件>`（或 `--from -` 读管道）核对：未落盘条目会给出 `remember` 建议命令，`--gate N` 可在未落盘条数超门槛时 exit 1。审计只读，不会自动补写记忆。

package/references/protocol.md

@@ -155,7 +155,7 @@ magic "YTMIDX1" (7B) | nonce(12B) | tag(16B) | ciphertext(JSON: {version, update
 | `remember <type> <subject> <statement> [--owner <id>] [--source <来源>] [--weight <0..>] [--verify] [--no-hint]` | 写入；同 subject+statement 已存在则更新 `updated` 且 `weight` 取 max；`--source` 记录来源；`--weight` 重要性权重；`--verify` 写后回读校验；`--no-hint` 关闭类型启发式提示 |
 | `recall [关键词] [--type T] [--limit N] [--year <yyyy>] [--agent <id>] [--owner <id>] [--all] [--unsafe]` | 索引+TF 打分匹配；读取分区过滤；越界（读其它智能体私密）默认拒绝，需 grant / identity=user / `--unsafe` 授权；项目级优先；默认 50 条；v0.17.0 起 `--year` 只读该年份分片（可重复传多次，不传即全量）|
 | `forget <文件>` | 删除（按路径或文件名）|
-| `archive [--days 180] [--threshold 0.4]` | 按盖棺分+年龄移入 `.archive/`（`vitality < threshold` 且超过 N 天）|
+| `archive [--days 180] [--threshold 0.4] [--dry-run] [--force] [--json]` | 按效用分 + 年龄移入 `.archive/`（`utility < threshold` 且超过 N 天）；v0.18.0 起默认豁免冷却期与 `evergreen` / `pinned`（`--force` 覆盖，immutable / BOUND 始终豁免）；`--dry-run` 只预览（零写入，不建快照 / 不写审计），无候选时不建整库快照，`--json` 输出结构化报告 |
 | `reindex` | 全量扫描重建 `index.json`（手动改 .md 后校正）|
 | `export [--out f.json]` | 导出全部记忆为 JSON |
 | `import <f.json>` | 从 JSON 导入（幂等）|
@@ -199,8 +199,9 @@ magic "YTMIDX1" (7B) | nonce(12B) | tag(16B) | ciphertext(JSON: {version, update
 ### MCP 工具分组（v0.15.0）
 
 - `yotta-memory serve --stdio --tools core`：只暴露 `context / recall / search / remember`，适合常驻 MCP。
-- `yotta-memory serve --stdio --tools full`：暴露现有 16 个工具，适合诊断、维护、导入导出与自我学习操作。
+- `yotta-memory serve --stdio --tools full`：暴露现有 17 个工具（v0.18.0 起含 `consolidate` 只读候选报告），适合诊断、维护、导入导出与自我学习操作。
 - 未指定 `--tools`：默认 `full`，保持旧配置兼容；`tools/list` 按当前分组返回，`tools/call` 越组调用会被拒绝并提示切换到 full。
+- v0.18.0 只读面（方案 A）：`archive.dryRun` / `maintain.capacity` / `context.audit` + `auditText`（内联文本，不接受文件路径、不读 stdin）/ `consolidate`（只出 propose 报告）。破坏性覆盖（`archive --force`、`consolidate --apply / --undo / --batches`）不暴露给 MCP，调用会被忽略或显式拒绝。
 
 ### remember / iam 扩展（v0.6.0）
 
@@ -267,10 +268,34 @@ magic "YTMIDX1" (7B) | nonce(12B) | tag(16B) | ciphertext(JSON: {version, update
 
 **权限与安全边界（不变式）**
 
-- consolidate / undo / batches 为管理动作，**不进 MCP**；maintain / archive 维持既有 MCP 暴露。
+- consolidate 的只读 propose 报告自 v0.18.0 起进 MCP（`consolidate` 工具，无 apply / undo / batches 入参）；`--apply` / `--undo` / `--batches` 为管理动作，**不进 MCP**（MCP 侧显式拒绝并提示改走本机 CLI，AI 不得代替用户执行 `--apply`）。maintain / archive 维持既有 MCP 暴露，v0.18.0 起追加只读 / 预演入参（`maintain.capacity`、`archive.dryRun`）。
 - 自动合并 / 压缩只写「公共 FACT + 本 owner 私密」；其它 owner 只预览，`--unsafe` 显式授权才处理。
 - 路径全程 `resolveWithinRoot` 校验；.archive 目标由引擎按 rel 生成。
 
+### v0.18.0：命中打点 / 容量水位 / 压缩审计 / 归档预演
+
+**命中打点（usage hit tracking）**
+
+- 写点：`recall`（含 MCP `recall` / `search`）命中、`explain <ref>`、`feedback --useful`、`context` 纳入条目。每次写 `hit_days`（按天聚合，信号 `s` / `g` / `u`，默认保留 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（不写对方文件）。
+- 加密库：私密条目命中后 owner 加密索引在同一次调用内同步，不需要额外 `reindex`。
+
+**容量水位与规模分级**
+
+- `maintain --capacity [--json]`：只读报告水位（条目 / 记忆文件字节 / 索引字节 / 单目录最大文件数 / 冷启动）、30 / 90 天活跃度、LRU / LFU 淘汰候选、晋升建议（90 天命中 ≥ `promotion_min_hits` 且不同查询 ≥ `promotion_min_queries`）；候选排除冷却期（`capacity_cooldown_days`）与常青条目（immutable / BOUND / `evergreen` / `pinned`）。
+- `doctor` 规模体检：`scale_warn_*` / `scale_info_*` 双阈值 + `checks.scale.metrics[]` 逐项 `ok | info | warning`；`doctor.ok` 仍只看 critical（info / warning 不锁定破坏性写入）。
+
+**consolidate 提案闸门与上下文压缩审计**
+
+- `consolidate` 默认等价 `--propose`（结构化报告 + `--json`，不写盘）；`--apply` 交互式需输入「X 组 / Y 条」确认串，非交互必须 `--yes`；首次启用显示一次数据生命周期说明。
+- `context --audit [--from <文件|->] [--json] [--gate N]`：核对被压缩掉的内容是否已落盘，输出已落盘 / 未落盘 / 无法判定与 `remember` 建议命令（subject 在非标点边界截断）；无 `--from` 时审计当前上下文包的 dropped 清单。只读。
+
+**archive 预演与无写入短路（2026-09-26 修正）**
+
+- `archive --dry-run`：只打印将归档清单（文件 / 类型 / 天龄 / 效用 / subject）与跳过统计，不动文件、不建事务快照、不写审计、不改索引；输出前缀「预览（未改动）」。
+- 无候选（apply 模式）时不创建整库事务快照；有候选时维持原闸门（doctor + 独立备份 + 异卷 + 事务快照），闸门拒绝时 exit 2。
+- `archive --json`：`{schemaVersion, root, mode: 'dry-run'|'apply', days, threshold, cooldown_days, force, candidates[], archived[], skipped{cooldown,evergreen,cross_owner}}`。
+
 ## 6. 与其他系统互操作
 
 - **git**：整个记忆库可纳入版本控制，回滚 / 审计 / 团队同步。

package/skill-manifest.json

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