@yottameta/yotta-memory 0.23.3 → 0.24.3

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## v0.24.3 (2026-11-14)
+
+- **CI 精度回归**：将命中打点后的 mtime 断言收紧到 Node 原生精度边界内（纳秒偏差 < 5µs）并保留可见毫秒不变；避免 Linux 上 `utimesSync` 的亚微秒浮点误差把正确行为误判为失败。
+
+## v0.24.2 (2026-11-14)
+
+- **跨平台修复**：Windows profile 绝对路径（如 `C:\Users\...\serve-profile.json`）在 Linux CI / 非 Windows 环境生成任务 XML 时不再被 `path.resolve()` 误拼成仓库内相对路径；新增 host-independent profile 路径解析并保留 XML 回归。
+
+## v0.24.1 (2026-11-14)
+
+- **自启服务 profile**：`lan enable` 在目标用户上下文解析并写入 `serve-profile.json`（memoryHome / runtimeHome / configDir / host / port / userId），Windows 任务 XML、Startup 兜底、systemd unit 与 crontab 均显式引用该 profile，不再依赖 S4U 启动环境的 `os.homedir()`。
+- **serve fail-closed**：新增 `serve --profile <文件>`；启动时校验 profile schema、绝对路径、memoryHome / runtimeHome 是否存在、userId 是否匹配，并原子覆盖进程环境。缺文件、空库、错误用户或非法路径均拒绝启动并给出中文提示。
+- **状态与迁移**：`lan status` 显示 profile 的 memoryHome / runtimeHome，与当前配置比较漂移；旧任务缺少 `--profile` 时提示重新执行 `lan enable`。重新执行 `lan enable` 即可迁移旧任务。
+- **验证**：新增 Windows task / Startup / Linux unit / crontab profile 回归，以及 `serve --profile` 的路径固化、缺库、错用户、CLI 缺文件用例；全量测试覆盖正常与失败路径。
+
+## v0.24.0 (2026-11-11)
+
+- **备份可靠性**：`backup status` 改为按 manifest `created` 解析时间排序，超过当前时间 15 分钟的备份标记 `future_timestamp` 并排除；manifest 缺失 / 不完整 / created 无效不参与健康判定；新增 `latest_valid` / `config_last_success` / `effective_last_success` / `source` / `anomalies`，`ensure-daily` 与默认备份体检复用同一选择逻辑。
+- **索引诊断**：新增 `yotta-memory index --stats [--json]`，只读输出当前存储体积、逻辑体积、tokens / statement / subject / tags / usage 字段占比、token / 拼音 token 统计和 v5 gzip 年份分片预估。
+- **索引 v5**：按逻辑体积 > 4 MB 或条目数 > 5000 触发 `index-<year>.json.gz`；兼容平铺 v4、分片 v4 与 v5 gzip；`--year` 只读命中的 gzip 分片；命中回写只重压对应分片；损坏 gzip fail-closed；备份白名单支持 `.json.gz`；`doctor` 新增 `index_logical_bytes` / `index_shards` / `index_format`。
+- **日级布局**：新写入改为 `facts/<yyyy>/<mm>/<dd>/` 与 `private/<owner>/<type>/<yyyy>/<mm>/<dd>/`，旧布局继续可读。
+- **布局迁移**：新增 `layout plan` / `layout apply --from-plan <文件> --yes` / `layout rollback --batch <id> --yes`；计划含旧 / 新路径、内容哈希与冲突；apply 写 journal，任一步失败逆序恢复；路径穿越与重复执行 fail-closed；加密 owner 无 key 时跳过。
+- **类型压力**：`doctor --json` 的 `checks.scale.type_pressure` 输出 `total` / `stale_180d` / `archive_candidates` / `growth_30d` / `stale_ratio` / `growth_ratio_30d` / `pressure_level`；按计划保留 7 天观察窗，暂不删除旧 `type_max` 兼容告警。
+- **扫描例外**：新增 `security/scan-policy.json` 精确例外，只接受规则 + 文件 + 整行 SHA-256 + 原因 + `review_by`；通配、路径穿越、无效哈希 fail-closed；内容变化或过期自动恢复命中；`--no-policy` 全量复核；`scan --policy-candidates --out <文件>` 只生成候选，不自动写策略。
+- **验证**：真实库副本公开索引 19,638,987 B → 3,221,545 B（16.4%），bench 指标前后一致；隔离副本 `facts/2026/10` 874 文件迁移后单目录最大 874 → 466，rollback 恢复；40 条扫描候选生成但未启用。
+
 ## v0.23.3 (2026-11-05)
 
 - 质量门禁与打包文档修正；发布前测试接入。

package/README.md

@@ -32,6 +32,8 @@
 ## Docs and release notes
 
 > 📖 The user-facing operations manual lives in [USER_GUIDE.md](USER_GUIDE.md).
+> 🆕 **v0.24.0 (structural capacity)**: `backup status` now selects valid manifest times and isolates future-dated anomalies; `index --stats` adds read-only field/byte analysis; index v5 uses gzip year shards while remaining v4-compatible; new writes use `yyyy/mm/dd` buckets with `layout plan/apply/rollback`; `doctor` adds four type-pressure indicators; `scan` supports exact rule + file + line-hash + expiry policies, while `--policy-candidates` only generates candidates.
+> 🆕 **v0.24.1 (autostart profile)**: `lan enable` writes a per-user `serve-profile.json`; Windows task XML, Startup fallback, systemd and crontab reference that absolute profile. `serve --profile <file>` pins memoryHome / runtimeHome / configDir and fails closed when paths or the Windows user do not match, preventing S4U / no-profile startup from landing on `C:\Users\Default\.yottamemory` and returning remote MCP 401.
 > 🆕 **v0.23.2 (ClawHub storefront)**: the ClawHub listing now ships an English-first bilingual summary and description (a dedicated `clawhub-dist/yotta-memory` publish copy), and the README gained the three usage cases above. Commands, options, output and the memory store format are unchanged.
 > 🆕 **v0.18.1 (distillation provenance + absolute dates + consolidation markers + rule-promotion suggestions + write discipline)**: `distill` now emits typed extraction lists (event / lesson / todo / growth / boundary-rule / other) with per-item `[source: file#L<a>-L<b>]` anchors, measured quality metrics and a skipped/boundary list, plus structured `--json`; `consolidate` rewrites relative dates ("yesterday / last week / this month / this year") into absolute dates based on each entry's `created` date and appends a consolidation marker to archived copies (`--undo` strips it); `maintain --rules` prints read-only "repeat pitfalls → promote to a rule" suggestions (default threshold 3, never writes BOUND automatically); the Memory Doctrine gained a 6-level conflict authority order and three write-discipline rules.
 
@@ -123,7 +125,7 @@ Each agent has a globally unique agent ID: it is the ownership key for private m
 
 ### Retrieval: semantic search (v0.8.0 + v0.9.0 embedding)
 
-- `remember` auto-builds the `index.json` index (version 4 since v0.8.1 with field weighting and pinyin tokens; public indexes over 5000 entries shard by year `index-<year>.json`; old indexes rebuild on first recall); recall defaults to semantic search — exact (field weighting: subject×3 / tags×2 / statement×1) + synonyms (built-in wordlist, extensible) + pinyin (full / initials, built-in 3755 common characters) + fuzzy (edit distance ≤ 2) + substring fallback, blended with utility score (0.65 × semantic + 0.35 × utility), zero-dependency.
+- `remember` auto-builds the index (version 5 since v0.24.0; logical size > 4 MB or more than 5000 entries uses `index-<year>.json.gz` year shards while remaining v4-compatible; old indexes rebuild on first recall); recall defaults to semantic search — exact (field weighting: subject×3 / tags×2 / statement×1) + synonyms (built-in wordlist, extensible) + pinyin (full / initials, built-in 3755 common characters) + fuzzy (edit distance ≤ 2) + substring fallback, blended with utility score (0.65 × semantic + 0.35 × utility), zero-dependency.
 - `recall --explain`: shows each hit's reason (exact / synonym / pinyin / fuzzy + field) and utility components.
 - **Candidate pre-filtering (v0.8.1)**: before semantic scoring, index tokens coarsely filter the candidate set (exact / synonym / pinyin / substring / fuzzy length gate) — hit set identical to v0.8.0; the `view` platform paginates by offset, fetching only the current page.
 - **Optional embedding plugin (v0.9.0)**: `recall --embedding <command>` or `config set embedding_cmd <command>` runs a local subprocess that accepts JSON on stdin and returns vectors on stdout; results are blended into the same ranking. Failures, timeouts, or malformed output automatically fall back to zero-dependency lexical recall.
@@ -317,7 +319,8 @@ Optional post-upgrade self-check: `yotta-memory config get` (confirm `memory_hom
 | `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 + X-Agent-Key auth) |
-| `yotta-memory lan enable [--onstart] / disable / status` | Autostart management (Windows: scheduled task with an S4U principal — runs silently in the background with no console window; `--onstart` starts at boot without a logon session, registration needs admin; non-admin auto-degrades to user-level silent Startup; Linux: systemd user unit, falls back to user crontab @reboot) |
+| `yotta-memory lan enable [--onstart] / disable / status` | Autostart management (Windows: scheduled task with an S4U principal — runs silently in the background with no console window; `--onstart` starts at boot without a logon session, registration needs admin; non-admin auto-degrades to user-level silent Startup; Linux: systemd user unit, falls back to user crontab @reboot). v0.24.1 persists a per-user `serve-profile.json`; `lan status` reports drift and old tasks lacking `--profile` |
+| `yotta-memory serve --profile <file>` | Read the per-user service profile, pin memory/runtime/config roots, validate absolute paths and the Windows user, and fail closed before opening the MCP port when a path is missing |
 | `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 |
 | `yotta-memory feedback <file> --useful|--useless [--reason <r>] [--undo]` | Usage feedback (useful/useless adjusts weight / confidence / feedback_net; --undo rolls back the last one) |

package/README.zh-CN.md

@@ -22,6 +22,8 @@
 </p>
 
 > 📖 面向用户的操作手册见 [USER_GUIDE.md](USER_GUIDE.md)。
+> 🆕 **v0.24.0（结构容量整改）**：`backup status` 按 manifest 时间选择有效备份并隔离未来时间异常；新增只读 `index --stats`，索引 v5 使用年份 gzip 分片并兼容 v4；新写入进入 `yyyy/mm/dd` 日级桶，`layout plan/apply/rollback` 支持可回滚迁移；`doctor` 增加类型压力四指标；`scan` 支持精确文件 + 规则 + 行哈希 + 有效期的例外策略，`--policy-candidates` 只生成候选、不自动启用。
+> 🆕 **v0.24.1（自启服务 profile）**：`lan enable` 在目标用户上下文生成 `serve-profile.json`；Windows 计划任务、Startup 兜底、systemd 与 crontab 都引用该绝对 profile。`serve --profile <文件>` 固定 memoryHome / runtimeHome / configDir，并在路径缺失或 Windows 用户不匹配时 fail-closed，避免 S4U / 无用户环境启动落到 `C:\Users\Default\.yottamemory` 空库后返回远端 MCP 401。
 > 🆕 **v0.23.2（ClawHub 门面）**：ClawHub 上的技能卡改为英文优先的双语摘要与描述（新增 `clawhub-dist/yotta-memory` 专属发布副本），README 首屏新增上面三条使用案例；命令、参数、输出与记忆库格式全部不变。
 > 🆕 **v0.20.0（上下文分页 + 画像驱逐修复）**：`memory.hook` 的 PREF 驱逐空转已修复——hook / paging 决策生效时，画像段落按实时可读条目渲染并套用同一套过滤；自我接入档案不进候选、不可驱逐。新增 `context.paging`：仅在显式 `--budget` 时调用，hook 先过滤、paging 再排序与分页；`drop` 始终安全应用，`order` 仅在 `complete:true` 且未截断时应用。`context --json` 新增 `paging` 块，`--explain` 增加 `[paging]` 轨迹。配置与协议见 `references/provider-protocol.md`。
 > 🆕 **v0.18.1（蒸馏溯源 + 日期绝对化 + 巩固标记 + 规则晋升建议 + 写入纪律）**：`distill` 新增分类型提取清单（事件 / 教训 / 待办 / 成长 / 规则边界 / 其他）+ 逐条 `[溯源: 文件#L<a>-L<b>]` + 实测质量指标 + 跳过与边界，`--json` 输出结构化报告；`consolidate` 摘要按条目 `created` 把「昨天 / 上周 / 本月 / 今年」写成绝对日期，归档副本写入巩固标记（`--undo` 剥离还原）；`maintain --rules` 只读给出「重复踩坑 → 建议升级为规则」（默认阈值 3，不自动写 BOUND）；记忆守则新增冲突权威顺序 6 层与写入纪律 3 条。
@@ -151,7 +153,7 @@
 
 ### 检索：语义检索（v0.8.0 + v0.9.0 embedding）
 
-- `remember` 时自动构建 `index.json` 索引（v0.8.1 起 version=4，含字段加权与拼音 token；公共索引超过 5000 条按年份分片 `index-<year>.json`；旧索引首次 recall 自动重建）；recall 默认语义检索——精确（字段加权：subject×3 / tags×2 / statement×1）+ 同义词（内置词表，可扩展）+ 拼音（全拼 / 首字母，内置 3755 常用字表）+ 模糊（编辑距离 ≤ 2）+ 子串兜底，并与效用分融合排序（0.65 × 语义 + 0.35 × 效用），零依赖。
+- `remember` 时自动构建索引（v0.24.0 起 version=5，含字段加权与拼音 token；逻辑体积 > 4 MB 或条目数 > 5000 时按年份写入 `index-<year>.json.gz`，同时兼容 v4 平铺 / 分片；旧索引首次 recall 自动重建）；recall 默认语义检索——精确（字段加权：subject×3 / tags×2 / statement×1）+ 同义词（内置词表，可扩展）+ 拼音（全拼 / 首字母，内置 3755 常用字表）+ 模糊（编辑距离 ≤ 2）+ 子串兜底，并与效用分融合排序（0.65 × 语义 + 0.35 × 效用），零依赖。
 - `recall --explain`：展示每条命中理由（精确 / 同义 / 拼音 / 模糊 + 字段）与效用分项。
 - **recall 候选预过滤（v0.8.1）**：语义打分前先用索引 token 粗筛候选集（精确 / 同义 / 拼音 / 子串 / 模糊长度门槛），命中集与 v0.8.0 完全一致；`view` 查看平台按偏移分页返回，一次只取当前页。
 - **可选 embedding 插件（v0.9.0）**：`recall --embedding <命令>` 或 `config set embedding_cmd <命令>`，本地子进程通过 stdin/stdout JSON 协议返回向量；结果并入同一套排序。插件失败、超时或输出非法时自动降级为零依赖词法检索。
@@ -359,7 +361,8 @@ bash install.sh --agent <智能体名称>
 | `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：计划任务 S4U 主体后台静默、不弹窗口；默认登录自启、`--onstart` 开机即启（无登录会话也可启动，注册需管理员），非管理员自动降级用户级 Startup 静默自启；Linux：systemd 用户单元，不可用时自动降级用户 crontab @reboot）|
+| `yotta-memory lan enable [--onstart] / disable / status` | 开机自启管理（Windows：计划任务 S4U 主体后台静默、不弹窗口；默认登录自启、`--onstart` 开机即启（无登录会话也可启动，注册需管理员），非管理员自动降级用户级 Startup 静默自启；Linux：systemd 用户单元，不可用时自动降级用户 crontab @reboot）。v0.24.1 生成每用户 `serve-profile.json`；`lan status` 检查路径漂移并提示缺少 `--profile` 的旧任务 |
+| `yotta-memory serve --profile <文件>` | 读取每用户服务 profile，固定记忆库 / 运行时 / 配置目录；路径缺失、非法或 Windows 用户不匹配时在监听端口前 fail-closed |
 | `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` 回滚最近一次）|

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、命中打点、容量水位、--capacity、--propose、上下文压缩审计、context --audit
-version: 0.23.3
+version: 0.24.3
 license: MIT
 ---
 
@@ -9,6 +9,16 @@ license: MIT
 
 > 一句话：元忆 —— 有权限边界的文件式智能体记忆（不注入、可 diff、能回滚；FACT 共享、PREF / BOUND / COMMIT 私密隔离）。
 
+- **结构容量整改（v0.24.0）**：备份状态按 manifest 时间选择有效备份并拒绝未来时间异常；
+  `index --stats` 只读分析索引字段体积与 gzip 预估；索引 v5 使用年份 gzip 分片并兼容 v4；
+  新写入进入 `yyyy/mm/dd` 日级桶，`layout plan/apply/rollback` 提供可预演、可回滚迁移；
+  `doctor` 增加类型压力四指标（保留 7 天观察窗）；`scan` 支持精确文件 + 规则 + 行哈希 +
+  有效期的例外策略，`--policy-candidates` 只生成候选、不自动启用。
+- **自启服务 profile（v0.24.1）**：`lan enable` 在目标用户上下文生成
+  `serve-profile.json`，Windows 计划任务、Startup 兜底、systemd 与 crontab
+  均显式引用该 profile；`serve --profile <文件>` 固化 memory_home / runtime_home /
+  config_dir，避免 S4U 或无用户环境启动时 `os.homedir()` 漂移为空库并导致远端 401。
+
 ## 这是什么
 
 - **文件式记忆标准**：记忆 = Markdown + YAML frontmatter 文件，git 可版本化，任何智能体可读，数据主权在用户本地。
@@ -155,7 +165,9 @@ yotta-memory doctor --json
 
 - `doctor` 检查记忆库根目录、加密库密钥文件、公共索引、`agents.json`、最近备份与**规模**（记忆条数 / 单目录最大文件数 / 索引总体积 / 索引冷启动耗时；只读，不产生写入）。
 - 规模阈值走 `config`：`scale_warn_entries`（默认 50000）/ `scale_warn_files_per_dir`（默认 500）/ `scale_warn_index_bytes`（默认 5242880）/ `scale_warn_cold_start_ms`（默认 2000）；超过阈值进 `checks.scale.warnings` 并计入 doctor warning，不锁定破坏性写入。
-- 规模明细在 `doctor --json` 的 `checks.scale`（`entries` / `files_per_dir` / `index_bytes` / `cold_start_ms` / `thresholds` / `level` / `warnings`）。
+- 规模明细在 `doctor --json` 的 `checks.scale`（`entries` / `files_per_dir` /
+  `index_bytes` / `index_logical_bytes` / `index_shards` / `index_format` /
+  `cold_start_ms` / `type_pressure` / `thresholds` / `level` / `warnings`）。
 - 严重异常（根目录缺失、密钥库缺文件、备份目录同卷）会返回非零退出码，并锁定破坏性写入。
 - `maintain --apply`、`consolidate --apply`、`merge`、`archive` 与 `--purge` 在执行前自动创建事务快照；未配置独立备份目录或快照失败时拒绝写入，原记忆保持不变。
 - 不提供 CLI 跳过快照的开关；`--allow-same-volume` 只用于 `backup create` 的显式临时备份，不会绕过破坏性写入门。
@@ -421,17 +433,17 @@ yotta-memory recall <关键词> --agent <id> --agent-key-file "<AI_HOME>/.yotta-
 
 ```
 <root>/
-├── facts/<yyyy>/<mm>/         # FACT 事实（公共可共享），新写入按年/月分层
-├── private/<owner>/<type>/<yyyy>/<mm>/  # PREF / BOUND / COMMIT，按智能体隔离
+├── facts/<yyyy>/<mm>/<dd>/    # FACT 事实（公共可共享），新写入按日级桶
+├── private/<owner>/<type>/<yyyy>/<mm>/<dd>/  # PREF / BOUND / COMMIT，按智能体隔离
 ├── private/<owner>/profile.md # 用户画像（明文库；加密库为 profile.md.enc）
 ├── private/<owner>/index.enc # 加密库：每 owner 加密索引（YTMIDX1，Owner Key 加密）
 ├── .archive/                 # 归档区（保留年/月分层，如 .archive/facts/2026/09/）
-├── index.json                # 公共 FACT 检索索引（加密库只含公共条目）
+├── index.json                # v5 索引 manifest；大库分片为 index-<year>.json.gz
 ├── keys/                     # 加密库密钥库：salt / <owner>.key.enc(UMK 包裹) / <owner>.key.recovery(恢复钥匙包裹) / recovery.key.enc / bindings/<id>.key.agent；legacy cache/<id>.key 不再加载
 └── agents.json               # 智能体身份登记表（唯一性）
 ```
 
-记忆文件 `<YYYY-MM-DD>-<NNNN>.md`，frontmatter 含 `type / subject / statement / confidence / created / updated / tags / immutable / scope / owner / source / weight / access_count / last_accessed`（`source` 记录来源、`weight` 重要性权重默认 1.0）；正文为记忆内容。**新写入按年/月分层**（如 `facts/2026/09/2026-09-25-0001.md`），读取时新旧路径同时兼容：v0.16 及更早的平铺文件（`facts/*.md`、`private/<owner>/<type>/*.md`）保持原位继续可读，**不做自动迁移**；写入去重也只覆盖当前年/月与平铺根，不会在大库上全量扫描。旧版根下平铺的 `prefs/` `bounds/` `commits/`（更早的布局）仍会在 `reindex`（或首次 recall 建索引）时按 frontmatter `owner` 自动迁移到 `private/<owner>/<type>/`。
+记忆文件 `<YYYY-MM-DD>-<NNNN>.md`，frontmatter 含 `type / subject / statement / confidence / created / updated / tags / immutable / scope / owner / source / weight / access_count / last_accessed`（`source` 记录来源、`weight` 重要性权重默认 1.0）；正文为记忆内容。**v0.24.0 起新写入按日级桶**（如 `facts/2026/09/25/2026-09-25-0001.md`），读取时新旧路径同时兼容：旧平铺、年/月桶继续可读，**默认不自动迁移**；需要消除超大月桶时用 `layout plan` 预演、`layout apply --from-plan <文件> --yes` 执行、`layout rollback --batch <id> --yes` 回滚。写入去重覆盖当前月与平铺根，不会在大库上全量扫描。旧版根下平铺的 `prefs/` `bounds/` `commits/`（更早的布局）仍会在 `reindex`（或首次 recall 建索引）时按 frontmatter `owner` 自动迁移到 `private/<owner>/<type>/`。
 
 归档保留分层：`archive` / `maintain --apply` 把记忆移入 `.archive/` 时按原年/月路径落位（不同月份的同名文件不会互相覆盖），旧平铺文件仍落到归档根。
 

package/USER_GUIDE.md

@@ -36,6 +36,7 @@
 - **自我学习 / 自我进化 / 自我提升（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`。v0.18.0 起 MCP 追加只读 / 预演能力（`archive.dryRun`、`maintain.capacity`、`context.audit` + 内联 `auditText`、`consolidate` 只出 propose 报告）；v0.18.1 追加 `maintain.rules`（只读规则晋升建议）。`archive --force` 与 `consolidate --apply / --undo` 只在命令行，MCP 调用会被忽略或拒绝。
+- **结构容量整改（v0.24.0）**：备份状态按有效 manifest 时间选择；`index --stats` 只读分析索引字段体积；索引 v5 使用年份 gzip 分片并兼容 v4；新写入按日级桶保存；`layout plan/apply/rollback` 提供可回滚布局迁移；`doctor` 增加类型压力四指标；`scan` 支持精确扫描例外与候选清单。
 
 ## 2. 安装（CLI + 技能）
 
@@ -290,7 +291,7 @@ yotta-memory recall <关键词> --agent <id> --agent-key-file "<AI_HOME>/.yotta-
 - `yotta-memory backup list` 查看备份；`backup doctor` 校验文件哈希；`backup restore <id> --to <新目录>` 恢复到新目录，不覆盖正在使用的记忆库。
 - `yotta-memory backup volumes` 只列出当前机器实际存在、可写、与记忆库异卷的路径；用户确认一次位置后，`backup setup --dir <目录>` 创建首份备份并默认启用每日自动备份（默认 03:30）。
 - Windows 使用 Task Scheduler，Linux 使用 systemd user timer（不可用时降级 cron），macOS 使用 LaunchAgent；`serve` 启动后与每 6 小时调用幂等 `backup ensure-daily` 补跑。
-- `yotta-memory backup status` 查看目录、计划、上次成功、最近失败与调度状态；`backup drill` 恢复到隔离副本，校验 manifest / 索引并解密一条测试私密。
+- `yotta-memory backup status` 查看目录、计划、有效备份 / 配置缓存、最近失败、异常备份与调度状态；未来时间、manifest 缺失或工作异常的备份不会参与健康判定。`backup drill` 恢复到隔离副本，校验 manifest / 索引并解密一条测试私密。
 - `yotta-memory backup drill <id> --probe [--against <库路径>]` 在恢复副本上追加六类只读基线探针（身份 / 近期 / 仅源库独有 / CJK / 操作规则 / owner 范围）；`--against` 指向源库时，备份没有落后于源库才算通过，探针失败即演练失败。
 - 备份目录与记忆库同卷时默认拒绝；这是一条防线，不替代独立盘备份。
 
@@ -312,6 +313,35 @@ yotta-memory recall <关键词> --agent <id> --agent-key-file "<AI_HOME>/.yotta-
 - `yotta-memory doctor --runtime [--json]`：检查 CLI / current / `runtime.json` / MCP 配置 / 运行中 server / 技能副本 / 身份模式漂移；每项漂移给出实际版本、期望版本、修复命令和是否阻断。可用 `--mcp-config <文件>`、`--skill-dir <目录>` 显式补充检查目标。
 - MCP `initialize` / `server/discover` 的 `serverInfo` 返回 `runtimePath` / `identityMode` / `toolProfile`，宿主可显示实际执行的运行时路径与工具分组，不再只看配置里的版本。
 
+## 3.11 结构容量、v5 索引与可回滚布局（v0.24.0）
+
+- `yotta-memory index --stats [--json]`：只读分析公共索引的存储体积、逻辑体积、字段占比、token / 拼音 token 数、gzip 年份分片预估与触发原因；不重建索引、不修改文件。
+- 索引 v5：逻辑体积 > 4 MB 或条目数 > 5000 时写 `index-<year>.json.gz`；继续读取 v4 平铺 / 分片；`recall --year` 与 `context --year` 只加载命中年份分片；gzip 损坏 fail-closed，不用残缺结果冒充成功。
+- 新写入布局：公共 `facts/<yyyy>/<mm>/<dd>/`，私密 `private/<owner>/<type>/<yyyy>/<mm>/<dd>/`；旧平铺与年/月桶继续兼容读取。
+- 布局迁移：
+  `yotta-memory layout plan [--threshold N] [--include-flat] [--json]`
+  → 审阅候选和冲突
+  → `yotta-memory layout apply --from-plan <文件> --yes`
+  → 出问题时 `yotta-memory layout rollback --batch <id> --yes`。
+  apply / rollback 都写 journal；默认只处理超过阈值的年/月桶，旧平铺不迁。
+- `doctor --json` 的 `checks.scale` 新增 `index_logical_bytes` / `index_shards` / `index_format` 与 `type_pressure`（总数 / 180 天陈旧 / 归档候选 / 30 天增长）；类型阈值按计划保留观察窗。
+- `scan` 精确例外：`security/scan-policy.json` 中每条必须同时匹配规则、文件、整行 SHA-256 与未过期的 `review_by`；内容变化或过期自动恢复命中。`scan --no-policy` 做全量复核；`scan --policy-candidates --out security/scan-policy.candidates.json` 只生成候选，不自动启用。
+
+## 3.12 每用户自启 profile（v0.24.1）
+
+- `yotta-memory lan enable` 在目标用户上下文解析 `memoryHome`、`runtimeHome`、
+  `configDir`、`host`、`port` 和 `userId`，写到该用户配置目录下的
+  `serve-profile.json`。不同用户的路径互不影响，不是代码或全机器共享常量。
+- Windows task XML、Startup 兜底、systemd unit 与 crontab 都引用该绝对 profile
+  路径。服务由 S4U 或无用户环境启动时，不再依赖 `os.homedir()`。
+- `yotta-memory serve --profile <文件>` 在监听端口前校验 profile schema、
+  绝对路径、memoryHome / runtimeHome 是否存在以及 Windows 用户是否匹配；
+  校验失败直接退出，不创建 `C:\Users\Default\.yottamemory` 空库。
+- `yotta-memory lan status` 显示 profile 中的记忆库和运行时路径，并与当前
+  设置比较漂移；旧任务命令缺少 `--profile` 时提示重新执行 `lan enable`。
+- 修改 `memory_home`、配置目录或 runtime 路径后，应重新执行
+  `yotta-memory lan enable --onstart` 更新 profile 和自启任务。
+
 ## 4. 便携记忆盘 · 记忆引擎主机篇
 
 场景：记忆放在一台主机上（Linux / Windows 均可），本机直接 CLI 读写；局域网内其它主机上的 AI 智能体经 MCP 远程接入。引擎主机只需装 CLI，不需要装任何 AI 智能体。
@@ -466,6 +496,8 @@ 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 index --stats [--json]` | 只读索引统计（存储 / 逻辑体积、字段占比、token、gzip 分片预估；不重建、不改文件）|
+| `yotta-memory layout plan [--threshold N] [--include-flat] [--out <文件>] [--json]` / `layout apply --from-plan <文件> --yes` / `layout rollback --batch <id> --yes` | 日级目录重平衡：预演候选与冲突、按 journal 执行、失败逆序回滚、按批次恢复原布局 |
 | `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 + 独立备份 + 事务快照）|
@@ -483,9 +515,9 @@ yotta-memory key claim <本智能体ID>
 | `yotta-memory distill [--owner <id>] [--subject <主题>] [--model <cmd>] [--out <路径>] [--json]` | 心理日志蒸馏（v0.8.0 统计摘要 / 主题画像 / 知识地图 + v0.18.1 分类型提取清单 / 质量指标 / 跳过与边界；每条带 `[溯源: 文件#L<a>-L<b>]`；`--json` 结构化输出）|
 | `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` 附带耗时后不可逐字节复算；全程只读）|
-| `yotta-memory scan [--path <目录>] [--gate <安全级别>] [--quarantine --yes] [--restore] [--id <批次>] [--json]` | 记忆库安全扫描（v0.17.0：七类 = 恶意指令 / Prompt 注入 / 凭证泄漏 / 数据外泄 / 护栏绕过 / 行为操纵 / 权限提升；五级 + `file:line` 证据；默认只报告、零网络零依赖；`--gate` 命中该级别及以上 exit 1；`--quarantine` 需 `--yes` 或交互确认，先把原文件备份到 `.memory-scan/quarantine/` 再替换命中行；`--restore` 还原；凭证片段打码不回显）|
+| `yotta-memory scan [--path <目录>] [--gate <安全级别>] [--no-policy] [--policy-candidates] [--out <文件>] [--quarantine --yes] [--restore] [--id <批次>] [--json]` | 记忆库安全扫描（v0.17.0：七类 + 五级 + `file:line` 证据；默认只报告；`--gate` 命中该级别及以上 exit 1；v0.24.0 起支持精确规则 + 文件 + 行哈希 + 有效期例外；`--no-policy` 全量复核；`--policy-candidates` 只生成候选；`--quarantine` 需 `--yes` 或交互确认；`--restore` 还原；凭证片段打码不回显）|
 
-类型：`FACT`（事实，共享）/ `PREF`（偏好）/ `BOUND`（边界）/ `COMMIT`（承诺），后三类按智能体物理分目录隔离（`private/<owner>/<type>/`）；v0.17.0 起新写入再按年/月分层（`facts/<年>/<月>/`、`private/<owner>/<type>/<年>/<月>/`），旧平铺文件留在原位继续可读，不做自动迁移。
+类型：`FACT`（事实，共享）/ `PREF`（偏好）/ `BOUND`（边界）/ `COMMIT`（承诺），后三类按智能体物理分目录隔离（`private/<owner>/<type>/`）；v0.24.0 起新写入按日级桶（`facts/<年>/<月>/<日>/`、`private/<owner>/<type>/<年>/<月>/<日>/`），旧平铺与年/月桶继续可读，默认不自动迁移。
 
 ## 7. 故障排查