@yottameta/yotta-memory 0.23.2 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-memory",
-  "version": "0.23.2",
+  "version": "0.24.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

@@ -94,7 +94,13 @@ yotta-memory recall <关键词> --agent <id> --agent-key-file "<AI_HOME>/.yotta-
 运行 `yotta-memory doctor`。它只读检查记忆库根目录、加密库密钥文件、公共索引、`agents.json` 与最近备份；`--json` 可输出机器可读结果。严重异常时会锁定 `maintain --apply`、`consolidate --apply`、`merge`、`archive` 与 `--purge` 等破坏性写入，`context` 也会在开工提醒中显示“破坏性写入已锁定”。先按 doctor 提示修复，再继续写操作。
 
 ## 17. 记忆库很大，检索能快一点吗？
-公共索引超过 5000 条会按年份分片（`index-<year>.json`）。只关心某一年时用 `yotta-memory recall <关键词> --year 2026`（可重复传多次）或 `yotta-memory context --year 2026`：引擎只读取命中年份的分片文件，不再把所有年份载入内存。不传 `--year` 时行为与旧版完全一致（全量读取）。规模体检看 `yotta-memory doctor` 的「规模」段（条数 / 单目录最大文件数 / 索引总体积），阈值用 `config set scale_warn_entries` 等键调整。
+v0.24.0 起索引为 v5：逻辑体积超过 4 MB 或条目数超过 5000 时按年份写入 gzip 分片（`index-<year>.json.gz`），同时兼容 v4。只关心某一年时用 `yotta-memory recall <关键词> --year 2026`（可重复传多次）或 `yotta-memory context --year 2026`：引擎只读取命中年份的分片文件。想先看字段体积与预估压缩收益，运行 `yotta-memory index --stats --json`（只读）。规模体检看 `yotta-memory doctor` 的 `checks.scale`（条数 / 单目录最大文件数 / 索引体积 / `index_format` / `type_pressure`），阈值用 `config set scale_warn_entries` 等键调整。
+
+## 17.1 某个年/月目录文件太多，怎么安全迁移到日级桶？
+先预演：`yotta-memory layout plan --threshold 500 --json`。计划只处理超过阈值的年/月桶，旧平铺默认不迁；有目标占用或哈希异常会拒绝生成可执行计划。审阅后运行 `yotta-memory layout apply --from-plan <计划文件> --yes`；失败会自动逆序恢复。需要还原时运行 `yotta-memory layout rollback --batch <id> --yes`。迁移期间应停止其它写入进程。
+
+## 17.2 历史安全语料被 scan 命中，怎样设置不掩盖新风险？
+用 `yotta-memory scan --policy-candidates --out security/scan-policy.candidates.json` 生成候选，再人工复核。正式策略写入 `security/scan-policy.json`，每条必须同时匹配 `rule`、`file`、整行 `line_sha256`、`reason` 和未过期的 `review_by`；通配、路径穿越、无效哈希一律忽略。行内容变化或过期后会自动恢复命中；随时可用 `scan --no-policy` 做全量复核。
 
 ## 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`。

package/references/protocol.md

@@ -1,4 +1,4 @@
-# yotta-memory 协议规范 v0.8.1
+# yotta-memory 协议规范 v0.24.0
 
 > 本文件定义 yotta-memory 记忆标准：存储位置、目录结构、文件格式、类型体系与 CLI 命令参考。
 > 目标：任何支持 Agent Skills 开放标准的智能体，装完即可读写同一份记忆。
@@ -17,24 +17,24 @@
 
 ```
 <root>/
-├── facts/                  # FACT 事实（公共可共享）
+├── facts/<yyyy>/<mm>/<dd>/ # FACT 事实（公共可共享；旧平铺 / 年/月桶兼容）
 ├── private/                # 私密区（按 owner 物理分目录）
 │   └── <owner>/            # 每个智能体一个子目录
-│       ├── prefs/          # PREF 偏好（该 owner 私密）
-│       ├── bounds/         # BOUND 边界（该 owner 私密）
-│       ├── commits/        # COMMIT 承诺（该 owner 私密）
+│       ├── prefs/<yyyy>/<mm>/<dd>/  # PREF 偏好（该 owner 私密）
+│       ├── bounds/<yyyy>/<mm>/<dd>/ # BOUND 边界（该 owner 私密）
+│       ├── commits/<yyyy>/<mm>/<dd>/ # COMMIT 承诺（该 owner 私密）
 │       ├── distills/       # 心理日志蒸馏产物（v0.8.0：distill 命令生成，私密）
 │       └── profile.md      # 用户画像（profile 命令生成，零推断，可再生成）
 ├── .archive/               # 归档区（archive / maintain / consolidate / merge 移入，v0.10.0 起带 owner）
 │   ├── facts/                # 公共 FACT 归档
 │   └── private/<owner>/<type>/  # 私密归档（PREF/BOUND/COMMIT，带 owner 防撞名）
-├── index.json              # 公共 FACT 索引 + TF 打分（加密库只含公共条目）
+├── index.json              # v5 manifest；大库分片为 index-<year>.json.gz（兼容 v4）
 ├── keys/                   # 加密库密钥库：salt / <owner>.key.enc(UMK 包裹) / <owner>.key.recovery(恢复钥匙包裹) / recovery.key.enc / bindings/<id>.key.agent；legacy cache/<id>.key 不再加载
 ├── agents.json             # 智能体身份登记表（iam 写入，唯一性强制）
 └── README.md               # 记忆库说明
 ```
 
-> **`index.json` 说明**：条目内的 `tokens` 字段是中文分词的「词频表」（v0.8.0 起含字段加权与拼音 token），供 recall 的 TF 打分 / 语义检索使用，**不是**访问令牌。真正的访问令牌由 `token` 命令生成，存放在 `<root>/.server/tokens.json`，仅在局域网 `serve` 模式下用于请求鉴权。v0.8.1 起索引 version=4（公共索引超过 5000 条按年份分片 `index-<year>.json`），旧索引首次 recall 自动重建。
+> **`index.json` 说明**：条目内的 `tokens` 字段是中文分词的「词频表」（v0.8.0 起含字段加权与拼音 token），供 recall 的 TF 打分 / 语义检索使用，**不是**访问令牌。真正的访问令牌由 `token` 命令生成，存放在 `<root>/.server/tokens.json`，仅在局域网 `serve` 模式下用于请求鉴权。v0.24.0 起索引 version=5：逻辑体积 > 4 MB 或条目数 > 5000 时使用 `index-<year>.json.gz` 年份分片，同时兼容 v4 平铺 / JSON 分片；旧索引首次 recall 自动重建。
 
 > **目录结构（v0.5.0）**：私密记忆按 `owner` 物理分目录存放于 `private/<owner>/<type>/`。旧版根下平铺的 `prefs/` `bounds/` `commits/` 会在 `reindex`（或首次 recall 建索引）时按 frontmatter `owner` 自动迁移到 `private/<owner>/<type>/`。**AI 读写红线**：记忆读写一律走 `yotta-memory` CLI / MCP 工具；禁止用 shell（`Get-ChildItem` / `Get-Content` / `cat` / `ls` / `type` 等）直接读改记忆库目录下的文件——否则会绕过 `scope/owner` 权限边界，读到其它智能体的私密内容。
 
@@ -157,6 +157,8 @@ magic "YTMIDX1" (7B) | nonce(12B) | tag(16B) | ciphertext(JSON: {version, update
 | `forget <文件>` | 删除（按路径或文件名）|
 | `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 后校正）|
+| `index --stats [--json]` | 只读分析索引存储 / 逻辑体积、字段占比、token 与 gzip 年份分片预估 |
+| `layout plan/apply/rollback` | 生成日级目录迁移计划、按 journal 执行、失败回滚或按批次恢复 |
 | `export [--out f.json]` | 导出全部记忆为 JSON |
 | `import <f.json>` | 从 JSON 导入（幂等）|
 | `profile [--owner <id>]` | 用户画像聚合（零推断，写 `private/<owner>/profile.md`；跨 owner 默认拒绝）|

package/skill-manifest.json

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