@yottameta/yotta-memory 0.13.2 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/CHANGELOG.md +40 -0
  2. package/README.md +51 -18
  3. package/README.zh-CN.md +54 -21
  4. package/SKILL.md +62 -21
  5. package/USER_GUIDE.md +36 -20
  6. package/assets/view.html +1 -1
  7. package/bin/yotta-memory.js +1262 -168
  8. package/package.json +1 -1
  9. package/references/faq.md +8 -2
  10. package/references/protocol.md +30 -8
  11. package/skill-manifest.json +1 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yottameta/yotta-memory",
3
- "version": "0.13.2",
3
+ "version": "0.16.0",
4
4
  "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.",
5
5
  "license": "MIT",
6
6
  "keywords": [
package/references/faq.md CHANGED
@@ -9,7 +9,7 @@
9
9
  `init` 默认初始化加密库（需主口令 + 恢复钥匙，请妥善保存）；明文库可用 `migrate` 升级为加密。私密区文件为 `.md.enc`，可 git 版本化。查看/授权用 `yotta-memory view`（口令解锁，浏览/授权/吊销 AI）；授权时一次性展示的 `agent_key` 请立即保存，服务端同时写 `keys/pending/<id>.key` 供该 AI 新会话用 `key claim` 领取。出现 `[YTM_MIGRATION_REQUIRED]` 说明还有 agent 未绑定，请由你在 `view` 平台逐个点「授权」完成重新授权（AI 只提醒、不代执行）。
10
10
 
11
11
  ## 3. 多智能体权限怎么隔离？
12
- 公共 FACT 所有智能体可读；PREF / BOUND / COMMIT 按 owner 物理隔离，调用方必须持有匹配的 `agent_key`（用户执行 `key bind <id>`，或在 `view` 平台授权获得）。owner ID 单独存在不构成认证，不授权 / 无 key 读不到。私密操作缺 key 时会输出 `[YTM_MIGRATION_REQUIRED]`；授权完成后该标记消失。AI 新会话用 `key status <id> --to <AI_HOME>` 检查，pending 存在则 `key claim <id> --to <AI_HOME>` 落到 `<AI_HOME>/.yotta-memory-agent-key`；吊销后旧 key 立即校验失败，需重新授权。
12
+ 公共 FACT 所有智能体可读；PREF / BOUND / COMMIT 按 owner 物理隔离，调用方必须持有匹配的 `agent_key`（用户执行 `key bind <id>`，或在 `view` 平台授权获得）。owner ID 单独存在不构成认证，不授权 / 无 key 读不到。私密操作缺 key 时会输出 `[YTM_MIGRATION_REQUIRED]`；授权完成后该标记消失。AI 新会话用 `key status <id>` 检查，pending 存在则 `key claim <id>` 落到 `<AI_HOME>/.yotta-memory-agent-key`；`AI_HOME` 默认规则由 claim / status 共用（显式 `--to` / `--agent-key-file` > `YOTTA_MEMORY_AGENT_HOME` / `YOTTA_MEMORY_AGENT_KEY_FILE` > Codex / OpenCode / 通用宿主默认），status 会显示 `checked` 与 `discovery`。吊销后旧 key 立即校验失败，需重新授权。
13
13
 
14
14
  ## 4. 记忆找不到了？
15
15
  先 `config get` 确认 `memory_home` 指向的库；再 `reindex` 重建索引（升级后索引版本变化会自动重建）；最后 `recall <关键词>` / `search <词>` 语义检索。跨项目记忆在项目级 `.yottamemory`。
@@ -20,14 +20,20 @@
20
20
  ## 6. 局域网（便携记忆盘）怎么连？
21
21
  引擎主机 `lan enable` 注册开机自启（Windows 计划任务 / Linux systemd）→ `token new --agent <id>` 生成 token；客户端配 `url: http://<主机IP>:8787/mcp` + `Authorization: Bearer <token>` + `X-Agent-Id: <id>` + `X-Agent-Key: <agent_key>`。同机 / 共享文件系统由 AI 用 `key status` / `key claim` 领取宿主 key；跨机不共享文件系统由用户通过密码管理器或安全文件传输放置，不走聊天明文。`lan status` 查状态。
22
22
 
23
+ ## 6.1 全局 CLI、MCP 或常驻服务版本不一致？
24
+ 先跑 `yotta-memory doctor --runtime`：它会列出 CLI、current、`runtime.json`、MCP 配置、运行中 server、技能副本与身份模式的漂移，并给出实际版本、期望版本、修复命令和是否阻断。用 `yotta-memory runtime install --from-current` 建立 `<runtimeRoot>/current` 稳定入口；升级用 `runtime install <tarball|版本>` + `runtime use <版本> --restart`，回滚用 `runtime rollback --restart`。`lan enable` 与备份调度只登记 `current/bin/yotta-memory.js`，不再写死版本目录。
25
+
23
26
  ## 7. MCP 工具没加载？
24
27
  检查客户端 `mcpServers` 已配置 yotta-memory（url + token + agent_key）；agent_key 应来自 `<AI_HOME>/.yotta-memory-agent-key` 或 MCP secret 注入，不把明文 key 写进对话。改配置后重启/重载会话。本机直连可不配 MCP，直接用 CLI。
25
28
 
29
+ ## 7.1 MCP 工具太多，想减少常驻工具？
30
+ 用 `serve --tools core` 启动，工具列表只保留 `context / recall / search / remember`；需要 `doctor`、`forget`、`maintain`、`distill` 等完整能力时改用 `--tools full`。未指定 `--tools` 时默认仍为 `full`，不会影响已有配置。
31
+
26
32
  ## 8. 记忆库在哪个目录？
27
33
  `yotta-memory config get` 查看；`config set memory_home <目录>` 改位置。项目级记忆用 `init --project`（存 `.yottamemory/` 随项目共享）。
28
34
 
29
35
  ## 9. 跨会话恢复上下文？
30
- 开工运行 `yotta-memory context`（身份 + 画像 + 近期记忆 + 边界 + 承诺），需要细节再 `recall <关键词>`。
36
+ 开工运行 `yotta-memory context`（身份 + 铁律 + 画像 + 长期摘要 + 近期走廊 + 近期高价值 + 边界 + 承诺 + 会话闭环契约），需要细节再 `recall <关键词>`；摘要优先来自 `consolidate` 产物，收工前按闭环契约复盘并检查关键结论是否落盘。
31
37
 
32
38
  ## 10. 备份与迁移？
33
39
  优先使用 `backup create --dir <独立盘目录>` 创建整库备份；`backup list` 查看，`backup doctor` 校验 SHA-256，`backup restore <id> --to <新目录>` 恢复到新目录。备份默认拒绝与记忆库同卷。`export --out 文件.json` 仍可用于跨工具迁移；公共 FACT 是明文文件也可直接 git 备份。v0.12.2 起，破坏性操作也会在写入前自动创建事务快照。
package/references/protocol.md CHANGED
@@ -41,7 +41,9 @@
41
41
  ## 2.5 智能体身份（谁在写 / 谁在读）
42
42
 
43
43
  - **agent ID 必须全局唯一**：`iam <id>` 写入 `agents.json`（记忆库根目录），唯一性强制——ID 已被其它主机 / 来源（含远端 token 登记）占用则拒绝，确认是同一智能体才 `--force`。
44
- - **当次身份声明**：`whoami` / MCP `agent_info` 读「当次显式身份」——CLI 用 `--agent`，MCP 用 per-process `YOTTA_AGENT_ID` + `YOTTA_MEMORY_AGENT_KEY` + `YOTTA_MEMORY_TRUST_ENV_AGENT=1`；远端用 `X-Agent-Id` + `X-Agent-Key` 请求头（经 token 绑定校验）。不接受用户级全局 fallback。
44
+ - **当次身份声明（v0.16.0）**：`whoami` / MCP `agent_info` 读「当次显式身份」——CLI 用 `--agent` + `--agent-key/--agent-key-file`；stdio MCP 用 `--agent-id` + `--agent-key-file`；HTTP / 远程 MCP 用 `Authorization` + `X-Agent-Id` + `X-Agent-Key` 请求头（经 token 绑定校验）。身份 env 已删除，不接受环境变量 fallback。
45
+ - **身份边界**：HTTP 鉴权模式缺少 `X-Agent-Id` 或 `X-Agent-Key` 直接 401；stdio 缺少 `--agent-id` / key 文件时，私密操作 fail-closed。CLI `--agent` 与 `--agent-id` 同时出现且不一致时拒绝启动。
46
+ - **AI_HOME（v0.14.0）**：`key status` / `key claim` 共用发现规则——显式 `--to <目录>` / `--agent-key-file <文件>` > `YOTTA_MEMORY_AGENT_HOME` / `YOTTA_MEMORY_AGENT_KEY_FILE` > 宿主默认（Codex `$CODEX_HOME` 或 `~/.codex`；OpenCode `$XDG_CONFIG_HOME/opencode`；通用 `~/.<agent_id>`），文件名统一为 `.yotta-memory-agent-key`。status 输出 `checked` 与 `discovery`。
45
47
  - **自我档案**：`iam` 自动写一条 PREF `subject=自我接入档案`（owner=自己），statement 为 `; ` 分隔的 key:value——`agent_id / host / memory_home / mcp_mode(stdio|http) / engine_url(仅远端) / token(仅远端；本机不存 token)`，可含 `agent_name / user_name / relationship`（`iam --name/--user/--relationship` 写入）。
46
48
  - **私密记忆必须有 owner**：PREF / BOUND / COMMIT 写入时未声明身份（owner 空）直接拒绝（公共 FACT 不受影响），从机制上防止「抄别人的 ID」。
47
49
 
@@ -92,7 +94,7 @@ immutable: false
92
94
  - **UMK（用户主密钥）**：主口令 PBKDF2-SHA256（600000 次迭代 + 随机 16B 盐，盐存 `keys/salt`）派生，永不落盘明文。
93
95
  - **Owner Key**：每 owner 随机 32B；被 UMK 包裹存 `keys/<owner>.key.enc`（头 `YTMKEY1`，AAD=`owner:<id>`），被恢复钥匙包裹存 `keys/<owner>.key.recovery`。
94
96
  - **恢复钥匙（RK）**：随机 32B；被 UMK 包裹存 `keys/recovery.key.enc`（AAD=`recovery`），初始化/迁移时向用户打印一次（base64）。忘口令时用户提供 RK → 解开 `*.key.recovery` → 重设口令。
95
- - **agent_key 绑定**：由用户执行 `key bind <id>` 或在 `view` 平台授权，生成 32 字节 agent_key，只展示一次；owner key 由 agent_key 包裹写入 `keys/bindings/<id>.key.agent`（AES-256-GCM），同时写临时待领取文件 `keys/pending/<id>.key`。AI 新会话用 `key status <id> --to <AI_HOME>` / `key claim <id> --to <AI_HOME>` 领取到 `<AI_HOME>/.yotta-memory-agent-key`，claim 成功后删除 pending。本机 MCP 用 `YOTTA_MEMORY_AGENT_KEY`，远程 MCP 用 `X-Agent-Key`，CLI 用 `--agent-key/--agent-key-file`；调用方必须提供 `agent_id + agent_key` 才能解出 owner key；UMK 永不接触 AI。`key revoke` 删除 binding 与 pending，旧 key 随即校验失败。`key list` 与私密操作失败时输出 `[YTM_MIGRATION_REQUIRED]`，AI 只负责把迁移步骤转达给用户。
97
+ - **agent_key 绑定**：由用户执行 `key bind <id>` 或在 `view` 平台授权，生成 32 字节 agent_key，只展示一次；owner key 由 agent_key 包裹写入 `keys/bindings/<id>.key.agent`（AES-256-GCM），同时写临时待领取文件 `keys/pending/<id>.key`。AI 新会话用 `key status <id>` / `key claim <id>` 领取到 `<AI_HOME>/.yotta-memory-agent-key`，需要时显式加 `--to` / `--agent-key-file`，claim 成功后删除 pending。stdio MCP 用 `--agent-key-file`，远程 MCP 用 `X-Agent-Key`，CLI 用 `--agent-key/--agent-key-file`；调用方必须提供 `agent_id + agent_key` 才能解出 owner key；UMK 永不接触 AI。`key revoke` 删除 binding 与 pending，旧 key 随即校验失败。`key list` 与私密操作失败时输出 `[YTM_MIGRATION_REQUIRED]`，AI 只负责把迁移步骤转达给用户。
96
98
 
97
99
  ### 密文记忆文件（`.md.enc`，头 `YTMENC1`）
98
100
  ```
@@ -158,7 +160,7 @@ magic "YTMIDX1" (7B) | nonce(12B) | tag(16B) | ciphertext(JSON: {version, update
158
160
  | `export [--out f.json]` | 导出全部记忆为 JSON |
159
161
  | `import <f.json>` | 从 JSON 导入（幂等）|
160
162
  | `profile [--owner <id>]` | 用户画像聚合（零推断，写 `private/<owner>/profile.md`；跨 owner 默认拒绝）|
161
- | `context [--limit N] [--owner <id>] [--budget N]` | 开工上下文包（stdout：身份 + 多智能体铁律 + 画像 + 近期记忆 + 边界 + 承诺；`--budget` 近期记忆字符预算）|
163
+ | `context [--limit N] [--owner <id>] [--budget N] [--focus <关键词>] [--explain]` | 开工上下文包（stdout：身份 + 多智能体铁律 + 画像 + 长期摘要 + 任务相关记忆 + 近期走廊 + 近期高价值 + 边界 + 承诺 + 会话闭环契约；`--budget` 控制动态记忆字符预算）|
162
164
  | `iam <id> [--name] [--user] [--relationship] [--force]` | 登记身份 + 自我档案（可选扩展显示名 / 用户 / 关系）|
163
165
 
164
166
 
@@ -169,14 +171,34 @@ magic "YTMIDX1" (7B) | nonce(12B) | tag(16B) | ciphertext(JSON: {version, update
169
171
  - 权限：profile.md 属私密区（按 owner）；跨 owner 生成默认拒绝（exit 3），需 `--owner user` / `--unsafe` / grant 授权。
170
172
  - profile.md 为生成物，可随时重新生成；不进入 index.json。
171
173
 
172
- ### context（开工上下文包，v0.6.0）
174
+ ### context（开工上下文包，v0.6.0 + v0.14.0）
173
175
 
174
- - `context [--limit N] [--owner <id>] [--budget N]`：stdout 输出开工上下文包（不落盘），含多智能体接入铁律段（可读 A/B/C、可写范围、违规红线）与五段：
176
+ - `context [--limit N] [--owner <id>] [--budget N] [--focus <关键词>] [--explain]`：stdout 输出开工上下文包（不落盘），含多智能体接入铁律段（可读 A/B/C、可写范围、违规红线）与以下部分：
175
177
  1. 身份：agent_id / agent_name / user_name / relationship / host / memory_home（读自我档案）
176
178
  2. 用户画像摘要：profile.md（不存在则自动生成一次或降级跳过）
177
- 3. 近期记忆：按 importance（confidence × recency + updated + weight + immutable）排序前 N 条（默认 10），读取分区过滤；`--budget` 时按剩余字符预算逐条放行（身份/铁律/画像/边界/承诺 必保）
178
- 4. 边界提醒：BOUND 全列（可读范围内）
179
- 5. 承诺 / 锚点：COMMIT 全列（可读范围内）
179
+ 2.5 长期理解摘要：优先加载 `consolidate` 产物（`source=consolidate` 或 tags `consolidate` + `summary`），默认最多 3 条，只注入 subject + statement；细节用 `recall` 下钻。
180
+ 2.6 任务相关记忆（`--focus`）：任务关键词命中条目。
181
+ 3. 近期走廊：按 `updated / created` 倒序取样，默认数量沿用 `--limit`，不受 utility 排序影响；排除摘要、BOUND / COMMIT 与已展示条目。
182
+ 4. 近期高价值记忆（补位）：按 importance + utility 融合排序，补足未进入走廊 / focus 的条目，按文件去重。
183
+ 5. 边界提醒：BOUND 全列（可读范围内）。
184
+ 6. 承诺 / 锚点：COMMIT 全列（可读范围内）。
185
+ 7. 本会话闭环契约：固定输出开工加载、进行中立即 `remember --verify`、收工前复盘检查 COMMIT / 会话小结。
186
+ - `--budget`：控制 focus / 近期走廊 / 近期高价值等动态记忆的字符预算；身份、铁律、画像、长期摘要、边界、承诺与会话闭环契约必保。
187
+
188
+ ### 运行时稳定入口与诊断（v0.16.0 M2/M3）
189
+
190
+ - `runtimeRoot` 默认位于 `~/.yottamemory/runtime`；布局为 `runtime.json` + `versions/<version>/` + `current`（Windows junction / Unix symlink）。
191
+ - `runtime install --from-current` 从当前完整 npm 包安装；`runtime install <tarball|版本>` 安装 tarball 或拉取指定版本；`runtime use <version>` 切换 current；`runtime rollback` 切回 previous。
192
+ - `runtime.json` 记录 `current / previous / versions[].treeHash / installedAt`；`runtime status` 报告 current 指针与版本目录漂移。
193
+ - stdio MCP、`lan enable`、备份调度只引用 `<runtimeRoot>/current/bin/yotta-memory.js`；`runtime use --restart` 尝试重启受管 server，失败时把 current 切回旧版本。
194
+ - `doctor --runtime` 检查 CLI / current / `runtime.json` / MCP 配置 / 运行中 server / 技能副本 / 身份模式；漂移项包含 actual / expected / fix / blocking。
195
+ - MCP `initialize` / `server/discover` 的 `serverInfo` 返回 `runtimePath` / `identityMode`（`headers` / `stdio-args`）/ `toolProfile`（`core` / `full`）。
196
+
197
+ ### MCP 工具分组（v0.15.0）
198
+
199
+ - `yotta-memory serve --stdio --tools core`：只暴露 `context / recall / search / remember`，适合常驻 MCP。
200
+ - `yotta-memory serve --stdio --tools full`：暴露现有 16 个工具，适合诊断、维护、导入导出与自我学习操作。
201
+ - 未指定 `--tools`：默认 `full`，保持旧配置兼容；`tools/list` 按当前分组返回，`tools/call` 越组调用会被拒绝并提示切换到 full。
180
202
 
181
203
  ### remember / iam 扩展（v0.6.0）
182
204
 
package/skill-manifest.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "slug": "yotta-memory",
4
4
  "name": "元忆",
5
5
  "package": "@yottameta/yotta-memory",
6
- "version": "0.13.2",
6
+ "version": "0.16.0",
7
7
  "trust": "yottameta",
8
8
  "install": {
9
9
  "idempotent": true