@yottameta/yotta-memory 0.12.0 → 0.12.1

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## v0.12.1 (2026-09-12)
+
+安装与更新文档修复（无功能变更）：
+
+- 明确区分两个 bin：`yotta-memory` 是引擎 CLI，`yotta-memory-install` 是技能安装器；`npx -y @yottameta/yotta-memory` 只临时运行引擎，不安装技能。
+- README 中英版、USER_GUIDE、SKILL、FAQ 补全安装 / 更新命令：更新技能统一使用 `npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <name>`（或 `--dir <技能目录>`）；全局安装后可运行 `yotta-memory-install`。
+- 修正 `bin/install.js` 头部注释中的错误示例，并新增 `test/docs-install-update.test.js` 防止两个 bin 的文档再次漂移。
+
 ## v0.12.0 (2026-09-12)
 
 **可靠性基线（误删事故整改）**：

package/README.md

@@ -23,6 +23,8 @@
 
 > 📖 The user-facing operations manual lives in [USER_GUIDE.md](USER_GUIDE.md).
 
+> 🆕 **v0.12.1**: installation and update docs now distinguish the engine CLI (`yotta-memory`) from the skill installer (`yotta-memory-install`), with copy-ready upgrade commands.
+
 > 🆕 **v0.12.0**: reliability baseline — `init` refuses to overwrite an existing store (`--attach` to attach); `forget` moves entries into `.trash/`; `backup create / list / doctor / restore` provides independent-volume backups with SHA-256 manifests.
 
 > 🆕 **v0.10.0**: compression & forgetting — `consolidate` turns old low-use memories on the same topic into one **provenance-carrying periodic summary** that stays searchable (originals archived; `consolidate --undo <batch>` restores everything); near-duplicate **auto-merge with confidence** (`maintain --dedup --apply`); **per-type decay curves** (FACT slow / PREF medium / COMMIT task-like fast / BOUND never decays); batch audit via `consolidate --batches`.
@@ -176,6 +178,13 @@ bash install.sh --dir <path>     # install to the given directory
 bash install.sh --list           # list agents -> default directories
 ```
 
+### Two commands, two jobs
+
+This package exposes two separate commands:
+
+- `yotta-memory` — the engine CLI that reads and writes the memory store. `npx -y @yottameta/yotta-memory` temporarily runs only this CLI; it does **not** install the skill.
+- `yotta-memory-install` — the skill installer. Install or update the skill with `npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <agent-name>` (or `--dir <skills-dir>`).
+
 > Method 1 uses the npm registry (npmmirror / npmjs) and does not depend on GitHub; Methods 2/3 use GitHub and may fail without a proxy in China.
 ## Example outputs
 
@@ -222,7 +231,17 @@ Two upgrade paths match the two install paths:
 npm i -g @yottameta/yotta-memory
 ```
 
-**Upgrade the skill**: rerun your install command from the `## Install` section (e.g. `npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <name>` or `bash install.sh --agent <name>`) to overwrite the old skill folder.
+**Upgrade the skill**: rerun the command that matches the way you installed it:
+
+```text
+npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <agent-name>
+npx -y --package @yottameta/yotta-memory yotta-memory-install --dir <skills-dir>
+bash install.sh --agent <agent-name>
+```
+
+If you installed the CLI globally, `npm i -g @yottameta/yotta-memory` updates both the engine and the `yotta-memory-install` command; then run `yotta-memory-install --agent <agent-name>` to refresh the skill.
+
+After updating, verify `yotta-memory --version` and the installed `yotta-memory/SKILL.md` frontmatter `version:`.
 
 **v0.10.0 upgrade notes** — upgrading touches no data: no migration, no reindex, no re-init needed. v0.10.0 does not change the memory file format, the `facts/` / `private/<owner>/<type>/` layout, or the index version, so existing stores open as-is.
 

package/README.zh-CN.md

@@ -23,6 +23,8 @@
 
 > 📖 面向用户的操作手册见 [USER_GUIDE.md](USER_GUIDE.md)。
 
+> 🆕 **v0.12.1**：安装与更新文档明确区分引擎 CLI（`yotta-memory`）和技能安装器（`yotta-memory-install`），并补齐可直接复制的升级命令。
+
 > 🆕 **v0.12.0**：可靠性基线——`init` 对已有记忆库默认拒绝覆盖（用 `--attach` 接入）；`forget` 先移入 `.trash/` 并留审计；`backup create / list / doctor / restore` 支持独立盘备份、SHA-256 清单校验和只恢复到新目录。
 
 > 🆕 **v0.10.0**：压缩遗忘——`consolidate` 周期摘要压缩（同主题旧记忆 → 带溯源摘要 + 原文归档，`--undo <batch>` 一键回滚）；近重复自动合并（`maintain --dedup` 置信度分档，`--apply` 批量执行）；分类型衰减（FACT 慢 / PREF 中 / COMMIT 任务类快 / BOUND 不衰减）；`consolidate --batches` 批次审计可查。
@@ -216,6 +218,13 @@ bash install.sh --dir <path>     # 装到指定目录
 bash install.sh --list           # 列出智能体 -> 默认目录
 ```
 
+### 两个命令，各管一件事
+
+这个包提供两个不同的命令：
+
+- `yotta-memory`：读写记忆库的引擎 CLI。`npx -y @yottameta/yotta-memory` 只是临时运行这个 CLI，**不会**安装技能。
+- `yotta-memory-install`：技能安装器。安装或更新技能必须使用 `npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <智能体名称>`（或 `--dir <智能体技能目录>`）。
+
 > 方式一走 npm 源（npmmirror / npmjs），不依赖 GitHub；方式二 / 三走 GitHub，国内无代理可能失败。
 ## 命令输出样例
 
@@ -262,7 +271,17 @@ bash install.sh --list           # 列出智能体 -> 默认目录
 npm i -g @yottameta/yotta-memory
 ```
 
-**升级技能**：重跑「安装」节中的命令（如 `npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <name>` 或 `bash install.sh --agent <name>`），覆盖旧版技能文件夹。
+**升级技能**：按你当初的安装方式重跑对应命令，覆盖旧版技能文件夹：
+
+```text
+npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <智能体名称>
+npx -y --package @yottameta/yotta-memory yotta-memory-install --dir <智能体技能目录>
+bash install.sh --agent <智能体名称>
+```
+
+如果你全局安装了 CLI，`npm i -g @yottameta/yotta-memory` 会同时升级引擎和 `yotta-memory-install` 命令；之后运行 `yotta-memory-install --agent <智能体名称>` 即可刷新技能。
+
+升级后请核对 `yotta-memory --version` 和已安装的 `yotta-memory/SKILL.md` frontmatter 中的 `version:`。
 
 **v0.10.0 升级提示**——升级不碰数据：无需迁移 / reindex / 重新 init。v0.10.0 没有改记忆文件格式、`facts/` 与 `private/<owner>/<type>/` 布局，也没有改索引版本，旧库打开即用。
 

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、防误删
-version: 0.12.0
+version: 0.12.1
 license: MIT
 ---
 
@@ -21,6 +21,13 @@ license: MIT
 - **压缩遗忘（v0.10.0）**：记忆库长期可用不膨胀——`consolidate` 周期摘要压缩（把超龄 + 低效用 + 长期闲置的同主题旧记忆归纳成**带溯源**的摘要，原文整体进 `.archive/`，`--undo` 一键回滚）；`maintain --dedup` 近重复**自动合并**（置信度分档，`--apply` 批量执行高置信组）；效用分时效改为**分类型衰减**（FACT 慢 / PREF 中 / COMMIT 任务类快 / BOUND 不衰减）；`consolidate --batches` 批次审计可查。
 - **可靠性基线（v0.12.0）**：`init` 对非空记忆库默认拒绝覆盖（`--attach` 接入现有库）；`forget` 先移入 `.trash/` 并写审计；新增 `backup volumes / setup / status / ensure-daily / schedule / drill`（用户确认真实独立卷后默认每日自动备份）与 `backup create / list / doctor / restore`。
 
+## 安装 / 更新（两个 bin）
+
+- `yotta-memory`：引擎 CLI，负责读写记忆库。`npx -y @yottameta/yotta-memory` 只是临时运行引擎，不会安装技能。
+- `yotta-memory-install`：技能安装器。安装或更新技能使用 `npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <name>`（或 `--dir <技能目录>`）。
+
+AI 更新流程：先运行 `yotta-memory --version` 记录当前引擎版本；升级 CLI 用 `npm i -g @yottameta/yotta-memory`；升级技能用 `npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <name>`（或原安装时使用的 `--dir` / `install.sh`）；完成后回读 `yotta-memory --version` 与已安装 `SKILL.md` 的 `version:`，两者不一致时不得声称更新成功。
+
 ## 何时使用（触发）
 
 - 用户说「记住」「别忘了」「记一笔」等保存类指令。

package/USER_GUIDE.md

@@ -58,7 +58,13 @@
 
 > CLI 与技能分工不同：CLI 让命令行能读写记忆；技能让 AI 知道「开工 recall 恢复上下文、重要信息 remember 落盘、收工归档」。只装 CLI 不装技能，AI 不会自动使用这套工作流。
 
-**更新：** `npm i -g @yottameta/yotta-memory` 升级 CLI（不带版本号即最新版），再把技能文件夹重新装进智能体（重复执行上面的技能安装命令即可）。
+**更新：**
+
+- 升级 CLI：`npm i -g @yottameta/yotta-memory`（不带版本号即最新版）。
+- 升级技能：`npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <name>`；如果你用 `--dir` 安装，把同一个目录再传一次。
+- 全局安装时：`npm i -g @yottameta/yotta-memory` 会同时升级引擎和安装器，之后可运行 `yotta-memory-install --agent <name>`。
+
+> `npx -y @yottameta/yotta-memory` 只是临时运行引擎 CLI，不会安装技能；技能安装器必须使用上面的 `--package ... yotta-memory-install` 形式，或全局安装后的 `yotta-memory-install` 命令。
 
 **卸载：** `npm rm -g @yottameta/yotta-memory`，并从智能体的 skills 目录删除整个 `yotta-memory` 文件夹。
 

package/bin/install.js

@@ -2,11 +2,11 @@
 /**
  * yotta-memory 跨平台安装器
  * 用法:
- *   npx -y @yottameta/yotta-memory --agent <name>  # 按智能体默认用户级目录安装（推荐）
- *   npx -y @yottameta/yotta-memory --dir PATH      # 装到指定目录（用户改了目录的智能体）
- *   npx -y @yottameta/yotta-memory -g              # 安装到全部已知智能体用户级目录
- *   npx -y @yottameta/yotta-memory                 # 安装到检测到的项目级目录
- *   npx -y @yottameta/yotta-memory --list          # 列出智能体 -> 默认目录
+ *   npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <name>  # 按智能体默认用户级目录安装（推荐）
+ *   npx -y --package @yottameta/yotta-memory yotta-memory-install --dir PATH      # 装到指定目录（用户改了目录的智能体）
+ *   npx -y --package @yottameta/yotta-memory yotta-memory-install -g              # 安装到全部已知智能体用户级目录
+ *   npx -y --package @yottameta/yotta-memory yotta-memory-install                 # 安装到检测到的项目级目录
+ *   npx -y --package @yottameta/yotta-memory yotta-memory-install --list          # 列出智能体 -> 默认目录
  */
 'use strict';
 const fs = require('fs');

package/bin/yotta-memory.js

@@ -22,7 +22,7 @@ const crypto = require('crypto');
 const http = require('http');
 const child_process = require('child_process');
 
-const VERSION = '0.12.0';
+const VERSION = '0.12.1';
 // MCP 协议（2026-07-28 无状态 + 2025-11-25 legacy 握手，dual-era）
 const MCP_PROTOCOL_MODERN = '2026-07-28';
 const MCP_PROTOCOL_LEGACY = '2025-11-25';

package/package.json

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

@@ -46,3 +46,10 @@
 
 ## 14. 半衰期 / 归档阈值怎么调？
 `yotta-memory config set maintain_decay_halflife_FACT 1000`（FACT 慢衰减，单位天）、`maintain_decay_halflife_PREF` / `maintain_decay_halflife_COMMIT` 同理；BOUND 固定不衰减。归档阈值：`config set maintain_archived_utility 0.3`、`maintain_archived_age 180`；consolidate 参数 `consolidate_min_age` / `consolidate_min_idle` / `consolidate_max_utility` / `consolidate_min_group` / `consolidate_period`。改完 `config get` 可复查；单次运行也可用 CLI 参数（如 `consolidate --min-age 90`）临时覆盖。
+
+## 15. 两个命令有什么区别？怎么更新？
+
+- `yotta-memory` 是引擎 CLI，负责读写记忆库；`npx -y @yottameta/yotta-memory` 只是临时运行引擎，**不会安装技能**。
+- `yotta-memory-install` 是技能安装器。安装或更新技能用 `npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <name>`；用 `--dir` 安装时传入同一个技能目录。
+- 更新 CLI：`npm i -g @yottameta/yotta-memory`。更新技能：重跑上面的 `--package ... yotta-memory-install` 命令，或全局安装后运行 `yotta-memory-install --agent <name>`。
+- 为什么在 `npx -y @yottameta/yotta-memory` 后面加 `--agent <name>` 没有安装技能？因为 npm 默认运行的是包内同名的 `yotta-memory` 引擎 bin，而不是 `yotta-memory-install`；必须用 `--package` 显式指定安装器 bin。