@yottameta/yotta-memory 0.23.0 → 0.23.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## v0.23.1 (2026-10-25)
+
+- **ClawHub 英文门面（无引擎变更）**：发布副本改为英文优先的双语 `summary` / `description`（英文在前、中文关键词保留在后）并补英文 tags，上线后 ClawHub 技能卡摘要由纯中文变为英文优先；构建与校验由独立发布副本流程覆盖，中文检索优化字段只增不减。
+- **README 使用案例**：英文 / 中文 README 首屏新增「使用案例」三条（跨会话恢复上下文 / 决策当场落盘 / 收工留锚点 + 压缩审计）。
+- 兼容性：命令、参数、输出与记忆库格式全部不变；本次仅展示层文案与发布元数据。
+
 ## v0.23.0 (2026-10-20)
 - **上下文包 COMMIT 段保留策略（根治上下文包无预算膨胀）**：开工上下文包第 6 段默认只展示最近 20 条 COMMIT，`weight ≥ 1.5` 或带 `pinned` / `evergreen` 标签的条目不受上限影响、始终展示；其余折叠为一行提示（不删除，`recall --type COMMIT` 仍可检索）。新配置键 `context_commits_limit`（0 = 全部展示，回旧行为）；BOUND 段保持全量（底线保证不变）。
 - **归档门槛与效用地板对齐（根治「库只长不瘦」）**：`maintain_archived_utility` 默认 0.35 → **0.55**（记忆默认 `confidence=1.0`，效用分地板约 0.42~0.47，旧门槛永远打不到）；按分类型半衰形成退役阶梯：COMMIT 约 6 个月 / PREF 约 13 个月 / FACT 约 17 个月（无再访问时，且需超 180 天龄；BOUND / immutable / pinned / evergreen 豁免不变）。`context` 的「归档提醒」升级为可执行：显示超龄条数与已达门槛条数，并给出 `maintain` 预览 / `--apply` 命令。

package/README.md

@@ -21,7 +21,18 @@
   <a href="https://github.com/YottaMeta/yotta-memory"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
 </p>
 
+## Usage cases
+
+**1. Stop losing context between sessions.** At the start of work the agent runs `yotta-memory context` and gets one package: identity, long-term summaries, a recent corridor, boundaries and commitments. There is no need to re-explain the project every session.
+
+**2. Remember a decision the moment it is made.** When the user says "remember this", the agent runs `yotta-memory remember <type> <subject> <statement> --verify` and reads the entry back. Fact types go to the shared FACT zone; preference, boundary and commitment entries stay in that agent's own isolated zone.
+
+**3. Wrap up without hand-carrying state.** Before the session ends the agent writes a COMMIT anchor; `maintain` / `consolidate` keep the store small over time, and `context --audit` checks whether anything important was dropped when the host compacted the conversation.
+
+## Docs and release notes
+
 > 📖 The user-facing operations manual lives in [USER_GUIDE.md](USER_GUIDE.md).
+> 🆕 **v0.23.1 (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.
 
 > 🆕 **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).

package/README.zh-CN.md

@@ -22,6 +22,7 @@
 </p>
 
 > 📖 面向用户的操作手册见 [USER_GUIDE.md](USER_GUIDE.md)。
+> 🆕 **v0.23.1（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 条。
 
@@ -60,6 +61,14 @@
 
 > 🆕 **v0.8.1**：`view` 用户查看平台改为服务端分页（记忆多了一次只渲染当前页，页码上下页）；`recall` 增加候选预过滤（语义检索前先粗筛候选集，命中集不变，记忆量大时不再逐条全量语义 / 模糊 / 编辑距离）；公共 `index.json` 超过 5000 条时按年份分片（`index-<year>.json`），避免单文件膨胀。
 
+## 使用案例
+
+**1. 不再丢上下文。** 开工时智能体跑 `yotta-memory context`，一次拿到身份、长期摘要、近期走廊、边界与承诺；不用每个会话重新解释项目。
+
+**2. 决策当场落盘。** 用户说「记住」时，智能体执行 `yotta-memory remember <类型> <主题> <内容> --verify` 并回读；FACT 进公共区，偏好 / 边界 / 承诺只进本智能体私密区。
+
+**3. 收工不留半截状态。** 会话结束前写一条 COMMIT 锚点；`maintain` / `consolidate` 让记忆库长期不膨胀，`context --audit` 核对上下文被宿主压缩时是否有重要内容没落盘。
+
 ## 核心价值
 
 多数记忆方案把「记住」做成了黑盒：数据进了数据库或云端，用户看得到内容却改不动、难以审计，更控制不了「哪个智能体能看到什么」。元忆换了一条路——把记忆还原成看得见、管得着的文件（公共 FACT 明文可审计，私密区机制级加密、用户可口令解锁）：

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.0
+version: 0.23.1
 license: MIT
 ---
 

package/bin/yotta-memory.js

@@ -25,7 +25,7 @@ const net = require('net');
 const child_process = require('child_process');
 const { AsyncLocalStorage } = require('async_hooks');
 
-const VERSION = '0.23.0';
+const VERSION = '0.23.1';
 const CLI_VALUE_OPTS = new Set(['--type', '--limit', '--days', '--out', '--owner', '--agent', '--agent-id', '--agent-key', '--agent-key-file', '--plugin-data', '--threshold', '--scope', '--host', '--port', '--dir', '--name', '--user', '--relationship', '--source', '--weight', '--budget', '--password', '--new-password', '--recovery-key', '--recovery-key-out', '--reason', '--merge', '--model', '--subject', '--embedding', '--focus', '--embedding-timeout', '--min-age', '--min-idle', '--max-utility', '--min-group', '--period', '--to', '--id', '--time', '--tools', '--mcp-config', '--skill-dir', '--year', '--evalset', '--k', '--seed', '--bootstrap', '--gate', '--against', '--template', '--path', '--from']);
 const CLI_FLAG_OPTS = new Set(['--project', '--all', '--unsafe', '--no-auth', '--stdio', '--onstart', '--from-current', '--restart', '--force', '--attach', '--allow-same-volume', '--verify', '--no-hint', '--encrypt', '--no-encrypt', '--password-stdin', '--json', '--manual', '--skip-schedule', '--useful', '--useless', '--undo', '--dry-run', '--apply', '--purge', '--dedup', '--batches', '--propose', '--audit', '--capacity', '--rules', '--explain', '--semantic', '--runtime', '--ablate', '--timing', '--baseline', '--probe', '--quarantine', '--restore', '--no-usage', '--yes', '--keep-memories', '--keep-identity']);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-memory",
-  "version": "0.23.0",
+  "version": "0.23.1",
   "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/skill-manifest.json

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