@yottameta/yotta-memory 0.8.5 → 0.8.7

package/CHANGELOG.md

@@ -1,8 +1,18 @@
+## v0.8.7 (2026-09-01)
+
+评测反馈优化（文档 + 错误提示，功能不变）。
+
+- 新增 `references/faq.md`：10 条常见问题 / 避坑（类型选错、私密区加密、多智能体权限、记忆找不到、忘记主口令、局域网连接、MCP 加载、记忆库位置、跨会话恢复、备份迁移）。
+- 错误提示友好化：顶层错误附「修复建议」人话（检查 memory_home、主口令与恢复钥匙等）。
+- README 中英：新增「命令输出样例」（init / remember / recall / context 屏幕输出示意）+「常见问题 FAQ 速查」。
+- SKILL.md：新增「常见问题 FAQ（速查）」小节，指向 references/faq.md。
+- 版本四件对齐 0.8.7（package.json / SKILL.md / CHANGELOG / 引擎 VERSION）。
+
 # 更新日志
 
 ## v0.8.5 (2026-08-29)
 
-安全修复（SkillHub 安全扫描发现高危，修复后三源同步升版）：
+安全修复（安全扫描发现高危，修复后三源同步升版）：
 
 - **MCP 命令执行入口封死**：MCP `distill` 不再接受 `--model`（`callTool` 在工具边界直接拒绝），远端智能体无法再借 MCP 在引擎主机执行任意命令。
 - **MCP 任意路径读写封死**：MCP `export` / `import` 的 `out` / `src` 必须落在记忆库根内（新增 `resolveWithinRoot` 校验，防 `..` 穿越），库外路径直接拒绝，与「远程只能读写记忆」承诺对齐。
@@ -19,7 +29,7 @@
 
 ## v0.8.3 (2026-08-28)
 
-中英双语 README 对齐（老张拍板「英文门面 + 中文全档」）：
+中英双语 README 对齐（确定「英文门面 + 中文全档」）：
 
 - **README.md 改为英文**：作为 GitHub / npm / ClawHub 首页的英文门面（翻译 + 精简，覆盖定位 / 核心价值 / 四类型 / 权限隔离 / 身份 / 语义检索 / 生命周期 / 对比 / 安装（CLI+技能双装）/ 升级 / CLI 用法 / 局域网共享 / 开发校验全流程）。
 - **新增 README.zh-CN.md**：原中文完整主文档整体平移，顶部加语言切换链接。

package/README.md

@@ -100,6 +100,21 @@ Each agent has a globally unique agent ID: it is the ownership key for private m
 - `export` / `import`: export the whole store to JSON / import from JSON; an intermediate format for migration and backup.
 - git: the whole store can be version-controlled — rollback / audit / team sync.
 
+## FAQ (quick reference)
+
+| Question | Answer (see references/faq.md) |
+|---|---|
+| Wrong memory type? | Hint only; forget and rewrite; --no-hint to disable |
+| Private encryption? | init encrypts by default (master password + recovery key); migrate to encrypt a plaintext store |
+| Multi-agent isolation? | FACT public; PREF/BOUND/COMMIT per-owner, grant via key authorize / view |
+| Memory not found? | config get -> reindex -> recall/search |
+| Lost master password? | reset-password with recovery key |
+| LAN connect? | lan enable + token new; client url+token |
+| MCP not loaded? | Check mcpServers + restart; use CLI directly |
+| Where is the store? | config get; project-level .yottamemory |
+| Cross-session resume? | Run context + recall at session start |
+| Backup / migrate? | export / import |
+
 ## Comparison with other approaches
 
 > Compared by solution type, not product names. Criteria: data sovereignty, deployment cost, permission boundaries, auditability, cross-agent ability.
@@ -151,6 +166,42 @@ bash install.sh --list           # list agents -> default directories
 ```
 
 > 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
+
+> Illustrative (actual output may vary by version) so you know what to expect on screen.
+
+**init**:
+
+```text
+Memory store initialized: D:/.yottamemory
+Master password set; recovery key: xxxx-xxxx-xxxx-xxxx (keep it safe)
+```
+
+**remember** (with verify):
+
+```text
+Recorded: D:/.yottamemory/facts/2026-09-01-0001.md
+[verify] read-back OK: facts/2026-09-01-0001.md
+```
+
+**recall**:
+
+```text
+3 memories (top 3):
+[FACT] subject: statement... (D:/.yottamemory/facts/xxx.md)
+```
+
+**context**:
+
+```text
+# Start-of-work context (yotta-memory context)
+## 1. Identity
+## 2. User profile summary
+## 3. Recent memories (top 10 by activity)
+## 4. Boundaries (BOUND)
+## 5. Commitments / anchors (COMMIT)
+```
+
 ## Upgrade
 
 Two upgrade paths match the two install paths:

package/README.zh-CN.md

@@ -139,6 +139,21 @@
 - **安全边界**：管理动作（init / config / token / lan / serve）不进 MCP，token 不远程暴露；远程智能体只能读写记忆，且路径限记忆库内（export/import 的 out/src 必须落在库内）、distill 不支持 `--model`（仅本地 CLI），不能改配置、不能管 token。
 - 完整操作步骤见上文「局域网多机共享」章节与 [USER_GUIDE.md](USER_GUIDE.md)。
 
+## 常见问题 FAQ（速查）
+
+| 问题 | 答案（详见 references/faq.md） |
+|---|---|
+| 类型选错？ | 只提示不阻止；forget 后重写；--no-hint 关提示 |
+| 私密区加密？ | init 默认加密（主口令+恢复钥匙）；明文库 migrate 升级 |
+| 多智能体权限？ | FACT 公共；PREF/BOUND/COMMIT 按 owner 隔离，需 key authorize / view 授权 |
+| 记忆找不到？ | config get 查位置 → reindex 重建索引 → recall/search |
+| 忘记主口令？ | 用恢复钥匙 reset-password（无私密区锁定的预期行为） |
+| 局域网怎么连？ | 引擎 lan enable + token new；客户端配 url+token |
+| MCP 没加载？ | 检查 mcpServers + 重启会话；本机直连用 CLI |
+| 记忆库在哪？ | config get；项目级 .yottamemory |
+| 跨会话恢复？ | 开工跑 context + recall |
+| 备份迁移？ | export / import |
+
 ## 与其他方案对比
 
 > 以下按方案类型对比，不涉及具体产品名称。判断标准：数据主权、部署成本、权限边界、可审计性、跨智能体能力。
@@ -190,6 +205,42 @@ bash install.sh --list           # 列出智能体 -> 默认目录
 ```
 
 > 方式一走 npm 源（npmmirror / npmjs），不依赖 GitHub；方式二 / 三走 GitHub，国内无代理可能失败。
+## 命令输出样例
+
+> 以下为示意输出（以实际版本为准），让你知道执行命令后屏幕上会出现什么。
+
+**init（初始化记忆库）**：
+
+```text
+初始化记忆库成功：D:\.yottamemory
+主口令已设置；恢复钥匙：xxxx-xxxx-xxxx-xxxx（请妥善保存）
+```
+
+**remember（写入记忆，带 verify 回读）**：
+
+```text
+已记录: D:\.yottamemory\facts\2026-09-01-0001.md
+[verify] 已写回读 OK: facts/2026-09-01-0001.md
+```
+
+**recall（检索）**：
+
+```text
+共 3 条记忆（前 3 条）：
+[FACT] 项目名: 描述……（D:\.yottamemory\facts\xxx.md）
+```
+
+**context（开工上下文包）**：
+
+```text
+# 开工上下文包（yotta-memory context）
+## 1. 身份
+## 2. 用户画像摘要
+## 3. 近期记忆（按活跃度前 10 条）
+## 4. 边界提醒（BOUND）
+## 5. 承诺 / 锚点（COMMIT）
+```
+
 ## 升级
 
 两种升级方式对应两种安装方式：

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 候选预过滤"
-version: 0.8.5
+version: 0.8.7
 license: MIT
 ---
 
@@ -73,7 +73,7 @@ license: MIT
 - 三角建模：情绪（措辞 / 标点 / 长度）→ 认知（归因 / 信念 / 控制感）→ 行为（作息 / 应对 / 执行）；三者冲突时优先行为与认知。
 - 共情至少到第 3 阶段：识别 → 理解 → 回应 → 验证。
 - 诚实声明：AI 是模式匹配非真感受，不伪装、不编造伪情感记忆。
-- 危机识别：不评判、持续在场、温和引导现实支持；不擅自越界联系第三方。
+- 危机识别：不评判、持续在场、温和引导现实支持；不擅自越界联系外部。
 - 对齐：回应时让积累的理解自然影响语气与措辞（让用户感到「被记得、被懂」），而非机械引用记忆条目。
 - 情感外包双刃剑：做增益真实生活的陪伴，不替代真实关系。
 
@@ -323,6 +323,16 @@ license: MIT
 ### 4.10 复用
 - 成功后优先复用现有连接；失败（token 吊销等）再回 4.3。
 
+## 常见问题 FAQ（速查）
+
+常见问题与避坑见 `references/faq.md`：
+- 类型选错 → 只提示不阻止；`forget` 后按正确类型重写；
+- 私密区加密 → `init` 默认加密（主口令+恢复钥匙），明文库 `migrate` 升级，`view` 平台口令解锁；
+- 多智能体权限 → FACT 公共、私密按 owner 隔离，需 `key authorize` / `view` 授权；
+- 记忆找不到 → `config get` 查位置 → `reindex` → `recall` / `search`；
+- 忘记主口令 → 用恢复钥匙 `reset-password`；
+- 局域网 → 引擎 `lan enable` + `token new`，客户端配 url+token。
+
 ## 渐进披露
 
 - 协议细节、目录结构与类型规则见 `references/protocol.md`，需要时读取，不要每次全读。

package/USER_GUIDE.md

@@ -77,7 +77,7 @@ yotta-memory config get                              # 查看记忆库位置
 ```bash
 yotta-memory profile                          # 生成用户画像（写 private/<owner>/profile.md）
 yotta-memory context --limit 10 --budget 1800 # 生成开工上下文包（身份+铁律+画像+近期记忆+边界+承诺，预算控 token）
-yotta-memory iam <id> --name 元忆 --user 老张 --relationship 伙伴   # 自我档案扩展显示名/用户/关系
+yotta-memory iam <id> --name 元忆 --user 用户 --relationship 伙伴   # 自我档案扩展显示名/用户/关系
 ```
 
 - `profile` 引擎零推断：只按类型 / 主题 / 标签归组呈现原文，画像结论由 AI 内部形成，不当面贴标签。

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.8.5';
+const VERSION = '0.8.7';
 const TYPES = ['FACT', 'PREF', 'BOUND', 'COMMIT'];
 const TYPE_DIRS = { FACT: 'facts', PREF: 'prefs', BOUND: 'bounds', COMMIT: 'commits' };
 const PUBLIC_DIR = 'facts';
@@ -3464,7 +3464,7 @@ async function main() {
   }
 }
 
-if (require.main === module) { main().catch(function (e) { console.error('错误: ' + (e && e.message ? e.message : String(e))); process.exit(2); }); }
+if (require.main === module) { main().catch(function (e) { console.error('错误: ' + (e && e.message ? e.message : String(e))); console.error('修复建议: 若与记忆库/密钥/权限有关，请检查 memory_home 路径、主口令与恢复钥匙，或运行 yotta-memory config get 确认位置；仍无法解决请把上面的错误信息反馈给开发者。'); process.exit(2); }); }
 module.exports = {
   VERSION: VERSION,
   userRoot: userRoot,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-memory",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "description": "Yuanyi (元忆) — boundary-aware, file-based memory for AI agents. File-based, zero-dependency, diff/rollback-able; FACT/PREF/BOUND/COMMIT four types (public shared / private isolated), user-level + project-level storage; v0.8 semantic search + usage feedback loop + rule-layer self-organization + psychological-log distillation (self-learning/self-evolving/self-improving).",
   "license": "MIT",
   "keywords": [
@@ -23,7 +23,8 @@
     "bin",
     "README.zh-CN.md",
     "NOTICE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "!scripts/test_*.py"
   ],
   "repository": {
     "type": "git",

package/references/faq.md

@@ -0,0 +1,33 @@
+# 元忆 FAQ / 避坑指南
+
+> 常见问题速查：记忆找不到、权限/加密困惑、连不上时先看这里。
+
+## 1. 记忆类型选错了怎么办？
+类型只在写入时提示、不阻止（FACT=公共 / PREF、BOUND、COMMIT=私密）。写错不影响已写入内容；想改类型可 `forget` 后按正确类型重写。不需要提示可用 `--no-hint`。
+
+## 2. 私密区加密怎么用？
+`init` 默认初始化加密库（需主口令 + 恢复钥匙，请妥善保存）；明文库可用 `migrate` 升级为加密。私密区文件为 `.md.enc`，可 git 版本化。查看/授权用 `yotta-memory view`（口令解锁，浏览/授权/吊销 AI）。
+
+## 3. 多智能体权限怎么隔离？
+公共 FACT 所有智能体可读；PREF / BOUND / COMMIT 按 owner 物理隔离，其他智能体需显式授权（`key authorize <id>` 或 `view` 平台授权）。不授权读不到，也不会被别的智能体读到。
+
+## 4. 记忆找不到了？
+先 `config get` 确认 `memory_home` 指向的库；再 `reindex` 重建索引（升级后索引版本变化会自动重建）；最后 `recall <关键词>` / `search <词>` 语义检索。跨项目记忆在项目级 `.yottamemory`。
+
+## 5. 忘记主口令了？
+用初始化时保存的**恢复钥匙**：`yotta-memory reset-password`。没有恢复钥匙则私密区无法解锁（这是加密的预期行为），公共 FACT 不受影响。
+
+## 6. 局域网（便携记忆盘）怎么连？
+引擎主机 `lan enable` 注册开机自启（Windows 计划任务 / Linux systemd）→ `token new --agent <id>` 生成 token；客户端配 `url: http://<主机IP>:8787/mcp` + `Authorization: Bearer <token>` + `X-Agent-Id: <id>`。`lan status` 查状态。
+
+## 7. MCP 工具没加载？
+检查客户端 `mcpServers` 已配置 yotta-memory（url + token）；改配置后重启/重载会话。本机直连可不配 MCP，直接用 CLI。
+
+## 8. 记忆库在哪个目录？
+`yotta-memory config get` 查看；`config set memory_home <目录>` 改位置。项目级记忆用 `init --project`（存 `.yottamemory/` 随项目共享）。
+
+## 9. 跨会话恢复上下文？
+开工运行 `yotta-memory context`（身份 + 画像 + 近期记忆 + 边界 + 承诺），需要细节再 `recall <关键词>`。
+
+## 10. 备份与迁移？
+`export --out 文件.json` 导出全部记忆；`import <文件.json>` 恢复。公共 FACT 是明文文件可直接 git 备份；私密区用 export（需解锁）。