@yottameta/yotta-memory 0.8.5 → 0.9.0

package/CHANGELOG.md

@@ -1,8 +1,29 @@
+## v0.9.0 (2026-09-01)
+
+召回质量与上下文选择升级。
+
+- **两阶段召回**：词法候选 + 可选本地 embedding 插件候选，统一按语义分与效用分融合排序。
+- **可选 embedding 插件**：`--embedding <command>` 或 `config set embedding_cmd <command>`；本地子进程、`stdin/stdout` JSON 协议、超时默认 3000ms、失败自动降级为词法召回。
+- **任务感知上下文**：`context --focus <关键词>` 新增任务相关记忆段，按身份 / 边界 / 承诺 / 画像 / 任务记忆 / 近期记忆优先级组装。
+- **选择解释**：`context --explain` 输出 included / dropped 与原因；`recall --explain` 继续显示命中理由并补充 embedding 分。
+- **MCP 同步**：`recall` / `search` 新增 `embedding` / `embeddingTimeout` / `explain` 参数；新增 `context` 工具。
+- **版本四件对齐**：package.json / SKILL.md / CHANGELOG.md / 引擎 VERSION = 0.9.0。
+
+## 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 +40,7 @@
 
 ## v0.8.3 (2026-08-28)
 
-中英双语 README 对齐（老张拍板「英文门面 + 中文全档」）：
+中英双语 README 对齐（确定「英文门面 + 中文全档」）：
 
 - **README.md 改为英文**：作为 GitHub / npm / ClawHub 首页的英文门面（翻译 + 精简，覆盖定位 / 核心价值 / 四类型 / 权限隔离 / 身份 / 语义检索 / 生命周期 / 对比 / 安装（CLI+技能双装）/ 升级 / CLI 用法 / 局域网共享 / 开发校验全流程）。
 - **新增 README.zh-CN.md**：原中文完整主文档整体平移，顶部加语言切换链接。

package/README.md

@@ -23,6 +23,8 @@
 
 > 📖 The user-facing operations manual lives in [USER_GUIDE.md](USER_GUIDE.md).
 
+> 🆕 **v0.9.0**: recall quality + context selection — optional local embedding plugin, `context --focus`, and `--explain` selection trace.
+
 > 🆕 **v0.8.5**: security hardening — MCP `distill` no longer accepts `--model`; MCP `export` / `import` paths are restricted to the memory root; CLI `distill --model` no longer shells out (allowlist-based).
 
 ## Core value
@@ -71,18 +73,19 @@ Each agent has a globally unique agent ID: it is the ownership key for private m
 - **No token locally**: local CLI / stdio direct connection bypasses the network and does not validate tokens; identity is declared via the agent's MCP `env.YOTTA_AGENT_ID`.
 - **Private memory requires an owner**: writing PREF / BOUND / COMMIT without declaring identity is rejected (public FACT is unaffected), mechanically preventing ID spoofing.
 
-### Profile & start-of-work context (v0.6.0)
+### Profile & start-of-work context (v0.6.0 + v0.9.0)
 
 - **profile**: aggregates `private/<owner>/` PREF / BOUND / COMMIT verbatim, grouped by type + subject + tags, written to `profile.md`; the engine infers nothing — profile conclusions are formed internally by the AI per the "memory discipline", never pasted as labels.
-- **context**: one-shot start-of-work package — multi-agent integration rules + identity + user profile digest + recent memory (importance-sorted) + boundary reminders + commitments/anchors; supports `--budget` character budget (constant tokens, does not grow with memory).
+- **context**: one-shot start-of-work package — multi-agent integration rules + identity + user profile digest + optional task-focused memory (`--focus`) + recent memory (importance-sorted) + boundary reminders + commitments/anchors; supports `--budget` character budget and `--explain` selection trace.
 - **Memory discipline**: SKILL.md embeds a rule layer (type red lines / proactive trigger capture / know-the-user three stages / psychological grounding & alignment / bottom lines / host isolation / anti-patterns).
 
-### Retrieval: semantic search (v0.8.0) + Chinese tokenization scoring
+### 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.
 - `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: protocol reserved (implemented in v0.9); without a plugin it degrades to zero-dependency automatically.
+- **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.
+- **Embedding cache**: vectors are cached under each memory root at `.embed/cache.json`, keyed by `sha256(command + text)`; only vectors are stored, not plaintext.
 - The `tokens` field of `index.json` is a Chinese-tokenization term-frequency table (for TF scoring), **not** an access credential; auth tokens live at `.server/tokens.json`.
 - Supports keywords, `--type` filter, `--limit` truncation, project-level priority.
 - **Root de-duplication (v0.6.5)**: when project and user roots point at the same directory, recall / context uniquify roots so a file shows once.
@@ -100,6 +103,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 +169,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:
@@ -170,9 +224,9 @@ npm i -g @yottameta/yotta-memory
 |---|---|
 | `yotta-memory init [--project] [--dir <dir>]` | Initialize the store (default user-level `~/.yottamemory/`; --dir sets an explicit location) |
 | `yotta-memory remember <type> <subject> <statement> [--owner <id>] [--source <src>] [--weight <0..>] [--verify] [--no-hint]` | Write a memory (same subject+statement auto-updates; --owner marks ownership; --source records origin; --weight importance, dedup takes max; --verify read-back; --no-hint disables type hints) |
-| `yotta-memory recall [keywords] [--type T] [--limit N] [--agent <id>] [--owner <id>] [--all] [--unsafe]` | Search memory (index + TF scoring, partitioned reads; cross-reading other agents' private is denied by default, needs grant / identity=user / `--unsafe`; project-level priority) |
+| `yotta-memory recall [keywords] [--type T] [--limit N] [--agent <id>] [--owner <id>] [--all] [--unsafe] [--explain] [--semantic] [--embedding <cmd>] [--embedding-timeout N]` | Search memory (semantic + utility ranking; optional local embedding plugin; partitioned reads; cross-reading other agents' private is denied by default, needs grant / identity=user / `--unsafe`; project-level priority) |
 | `yotta-memory profile [--owner <id>]` | Generate a user profile (aggregates `private/<owner>` verbatim, zero inference, writes `profile.md`; cross-owner denied by default) |
-| `yotta-memory context [--limit N] [--owner <id>] [--budget N]` | Generate the start-of-work package (identity + multi-agent rules + profile + recent memory + boundaries + commitments; --budget budgets recent-memory chars, constant tokens) |
+| `yotta-memory context [--limit N] [--owner <id>] [--budget N] [--focus <text>] [--explain] [--embedding <cmd>]` | Generate the start-of-work package (identity + multi-agent rules + profile + task-focused memory + recent memory + boundaries + commitments; --budget caps chars, --focus adds task relevance, --explain shows included/dropped) |
 | `yotta-memory forget <file>` | Delete a memory (by type-dir path or file name) |
 | `yotta-memory archive [--days 180] [--threshold 0.4]` | Archive old memory (final score + age; immutable excluded) |
 | `yotta-memory reindex` | Rebuild the index (after manually editing .md) |
@@ -250,7 +304,7 @@ Register the connection in the agent's MCP config (`url` + two headers):
 }
 ```
 
-Once connected, MCP tools (remember / recall / search / forget / archive / reindex / export / import / agent_info) read/write memory and confirm identity; management actions (init / config / token / lan / serve) are not exposed via MCP, and token management is never exposed remotely. MCP `export` / `import` paths are restricted inside the memory root, and MCP `distill` does not support `--model` (local CLI only). `X-Agent-Id` must match the token's registered agent; read-partition rules are the same as the CLI (FACT public-readable, PREF / BOUND / COMMIT private).
+Once connected, MCP tools (remember / recall / search / context / forget / archive / reindex / export / import / agent_info) read/write memory and confirm identity; management actions (init / config / token / lan / serve) are not exposed via MCP, and token management is never exposed remotely. MCP `export` / `import` paths are restricted inside the memory root, MCP `distill` does not support `--model`, and MCP never accepts a raw embedding command from remote callers — the local embedding plugin must be configured on the engine host with `config set embedding_cmd`. `X-Agent-Id` must match the token's registered agent; read-partition rules are the same as the CLI (FACT public-readable, PREF / BOUND / COMMIT private).
 
 ### Location persistence
 

package/README.zh-CN.md

@@ -23,6 +23,8 @@
 
 > 📖 面向用户的操作手册见 [USER_GUIDE.md](USER_GUIDE.md)。
 
+> 🆕 **v0.9.0**：召回质量与上下文选择——可选本地 embedding 插件、`context --focus`、`--explain` 选择解释。
+
 > 🆕 **v0.8.5**：安全加固——MCP `distill` 不再接受 `--model`；MCP `export` / `import` 路径限记忆库内；CLI `distill --model` 不再走 shell（改为允许清单）。
 
 > 🆕 **v0.8.2**：发布元数据修复——三次源重发带 `--name 元忆 yotta-memory`，修复 ClawHub 展示名缺失中文（原为裸 `yotta-memory`）；无功能变更。
@@ -98,18 +100,19 @@
 - **本机免 token**：本机 CLI / stdio 直连不经网络、不校验 token；身份经该智能体 MCP 配置的 `env.YOTTA_AGENT_ID` 声明。本机多个智能体各自声明唯一 ID，互不撞。
 - **私密记忆必须有 owner**：写 PREF / BOUND / COMMIT 时未声明身份会被拒绝（公共 FACT 不受影响），从机制上防止「抄别人的 ID」。
 
-### 画像与开工上下文（v0.6.0）
+### 画像与开工上下文（v0.6.0 + v0.9.0）
 
 - **profile**：聚合 `private/<owner>/` 下 PREF / BOUND / COMMIT 原文，按 type + subject + tags 归组，写 `profile.md`；引擎零推断，画像结论由 AI 依据「记忆守则」内部形成，不当面贴标签。
-- **context**：一键生成开工上下文包——多智能体接入铁律 + 身份 + 用户画像摘要 + 近期记忆（按 importance 排序）+ 边界提醒 + 承诺 / 锚点；支持 `--budget` 字符预算（token 恒定，不随记忆膨胀）。
+- **context**：一键生成开工上下文包——多智能体接入铁律 + 身份 + 用户画像摘要 + 任务相关记忆（`--focus`，v0.9.0）+ 近期记忆（按 importance 排序）+ 边界提醒 + 承诺 / 锚点；支持 `--budget` 字符预算与 `--explain` 选择解释。
 - **记忆守则**：SKILL.md 内置规则层（类型红线 / 主动捕获触发信号 / 了解用户三阶段四手法 / 心理学底座与对齐 / 底线与边界 / 宿主隔离 / 反模式），让 AI「越用越懂」有章法。
 
-### 检索：语义检索（v0.8.0）+ 中文分词打分
+### 检索：语义检索（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 × 效用），零依赖。
 - `recall --explain`：展示每条命中理由（精确 / 同义 / 拼音 / 模糊 + 字段）与效用分项。
 - **recall 候选预过滤（v0.8.1）**：语义打分前先用索引 token 粗筛候选集（精确 / 同义 / 拼音 / 子串 / 模糊长度门槛），命中集与 v0.8.0 完全一致；`view` 查看平台按偏移分页返回，一次只取当前页。
-- 可选 embedding 插件：协议预留（v0.9 实装），无插件自动零依赖降级。
+- **可选 embedding 插件（v0.9.0）**：`recall --embedding <命令>` 或 `config set embedding_cmd <命令>`，本地子进程通过 stdin/stdout JSON 协议返回向量；结果并入同一套排序。插件失败、超时或输出非法时自动降级为零依赖词法检索。
+- **向量缓存**：向量缓存在各记忆根下 `.embed/cache.json`，键为 `sha256(命令 + 文本)`；只存向量，不存明文。
 - `index.json` 的 `tokens` 字段是中文分词的词频表（TF 打分用），**不是**访问凭证；鉴权令牌在记忆目录下 `.server/tokens.json`。
 - 支持关键词、`--type` 过滤、`--limit` 截断、项目级优先。
 - **根位置去重（v0.6.5）**：当项目级与用户级记忆库指向同一目录（如 cwd = home 或其父）时，`recall` / `context` 自动唯一化根，同一文件只展示一次。
@@ -139,6 +142,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 +208,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）
+```
+
 ## 升级
 
 两种升级方式对应两种安装方式：
@@ -210,9 +264,9 @@ npm i -g @yottameta/yotta-memory
 |---|---|
 | `yotta-memory init [--project] [--dir <目录>]` | 初始化记忆库（默认用户级 `~/.yottamemory/`；--dir 显式指定位置）|
 | `yotta-memory remember <type> <subject> <statement> [--owner <id>] [--source <来源>] [--weight <0..>] [--verify] [--no-hint]` | 写入记忆（同 subject+statement 自动更新；--owner 标注归属；--source 记录来源；--weight 重要性权重、去重取 max；--verify 写后回读；--no-hint 关闭类型提示）|
-| `yotta-memory recall [关键词] [--type T] [--limit N] [--agent <id>] [--owner <id>] [--all] [--unsafe]` | 检索记忆（索引+TF 打分，读取分区过滤；越界读其它智能体私密默认拒绝，需 grant / identity=user / `--unsafe`；`--agent <其它>` 仅作身份声明、不授予跨读；项目级优先）|
+| `yotta-memory recall [关键词] [--type T] [--limit N] [--agent <id>] [--owner <id>] [--all] [--unsafe] [--explain] [--semantic] [--embedding <命令>] [--embedding-timeout N]` | 检索记忆（语义+效用分排序；可选本地 embedding 插件；读取分区过滤；越界读其它智能体私密默认拒绝，需 grant / identity=user / `--unsafe`；`--agent <其它>` 仅作身份声明、不授予跨读；项目级优先）|
 | `yotta-memory profile [--owner <id>]` | 生成用户画像（聚合 `private/<owner>/` 原文，零推断，写 `profile.md`；跨 owner 默认拒绝）|
-| `yotta-memory context [--limit N] [--owner <id>] [--budget N]` | 生成开工上下文包（身份 + 多智能体铁律 + 画像 + 近期记忆 + 边界 + 承诺；--budget 近期记忆字符预算，token 恒定）|
+| `yotta-memory context [--limit N] [--owner <id>] [--budget N] [--focus <关键词>] [--explain] [--embedding <命令>]` | 生成开工上下文包（身份 + 多智能体铁律 + 画像 + 任务相关记忆 + 近期记忆 + 边界 + 承诺；--budget 字符预算；--focus 任务聚焦；--explain 输出 included/dropped 选择解释）|
 | `yotta-memory forget <文件>` | 删除一条记忆（按类型目录路径或文件名）|
 | `yotta-memory archive [--days 180] [--threshold 0.4]` | 归档旧记忆（盖棺分+年龄，immutable 除外）|
 | `yotta-memory reindex` | 重建索引（手动改 .md 后校正）|
@@ -290,7 +344,7 @@ yotta-memory recall --type FACT --limit 10
 }
 ```
 
-连接后可通过 MCP tools（remember / recall / search / forget / archive / reindex / export / import / agent_info）读写记忆与确认身份；管理动作（init / config / token / lan / serve）不进 MCP，token 管理不远程暴露；MCP export/import 路径限记忆库内、distill 不支持 `--model`（仅本地 CLI）。`X-Agent-Id` 必须与 token 登记的智能体一致；读取分区规则与 CLI 相同（FACT 公共可读，PREF / BOUND / COMMIT 私密隔离）。
+连接后可通过 MCP tools（remember / recall / search / context / forget / archive / reindex / export / import / agent_info）读写记忆与确认身份；管理动作（init / config / token / lan / serve）不进 MCP，token 管理不远程暴露；MCP export/import 路径限记忆库内、distill 不支持 `--model`，MCP 也不接受远端传入 embedding 命令——embedding 插件只能由引擎主机本地 `config set embedding_cmd` 配置。`X-Agent-Id` 必须与 token 登记的智能体一致；读取分区规则与 CLI 相同（FACT 公共可读，PREF / BOUND / COMMIT 私密隔离）。
 
 ### 位置持久化
 
@@ -309,4 +363,4 @@ yotta-memory config get
 
 ## 许可证
 
-MIT © YottaMeta —— 详见 [LICENSE](./LICENSE)。
+MIT © YottaMeta —— 详见 [LICENSE](./LICENSE)。

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
+description: "元忆 —— 有权限边界的文件式智能体记忆。文件式、零依赖、可 diff/可回滚：让任何 AI 智能体活过会话，开工 recall 恢复上下文、重要信息 remember 落盘、收工归档。类型体系 FACT（公共共享）/ PREF / BOUND / COMMIT（私密隔离）。触发：记住、别忘了、记一笔、记忆、remember、recall、跨会话、上次说到、续测、交接、归档、记忆盘、共享记忆、局域网记忆、画像、开工上下文、记忆守则、profile、context、越用越懂、语义检索、反馈、维护、蒸馏、feedback、maintain、distill、explain、自我学习、自我进化、自我提升、查看平台分页、recall 候选预过滤、任务相关记忆、--focus、--embedding"
+version: 0.9.0
 license: MIT
 ---
 
@@ -18,6 +18,7 @@ license: MIT
 - **双级存储**：用户级 `~/.yottamemory/`（跨项目）+ 项目级 `.yottamemory/`（随项目共享）。
 - **越用越懂**：`profile` 聚合用户画像（引擎零推断，只归组原文）+ `context` 一键生成开工上下文包（身份 + 画像 + 近期记忆 + 边界 + 承诺）+ SKILL「记忆守则」规则层；只注入规则与机制，不注入人格数据（出厂零数据）。
 - **自我学习 / 自我进化 / 自我提升（v0.8.0）**：`recall` 语义检索（同义词 / 拼音 / 字段加权 / 模糊匹配，零依赖）；`feedback` 显式使用反馈闭环（useful / useless → weight / confidence / feedback_net 演化，越用越懂）；`maintain` 规则层自组织（统一效用分 + 年龄自动归档 / 遗忘候选 / 去重，默认 dry-run，immutable / BOUND 豁免）；`distill` 心理日志蒸馏（统计摘要 / 主题画像 / 知识地图，可选 `--model` 外部模型增强）；`explain` 查看单条记忆效用分项。
+- **召回质量与上下文选择（v0.9.0）**：`recall` 支持可选本地 embedding 插件（`--embedding <command>` / `config set embedding_cmd <command>`）；`context --focus <关键词>` 生成任务感知上下文；`--explain` 输出选择 trace，无插件时自动降级为词法检索。
 
 ## 何时使用（触发）
 
@@ -28,7 +29,7 @@ license: MIT
 
 ## 核心流程
 
-1. **开工定向**：先按「开工第一步：确认记忆位置 + 智能体身份」检测记忆库与身份，再运行 `yotta-memory context`（主注入：身份 + 用户画像 + 近期记忆 + 边界 + 承诺）恢复上下文，需要细节再 `yotta-memory recall <关键词>`；项目级记忆优先，其次用户级。
+1. **开工定向**：先按「开工第一步：确认记忆位置 + 智能体身份」检测记忆库与身份，再运行 `yotta-memory context`（主注入：身份 + 用户画像 + 近期记忆 + 边界 + 承诺）恢复上下文，需要细节再 `yotta-memory recall <关键词>`；若有明确任务关键词，用 `context --focus <关键词>` 获得任务相关记忆；项目级记忆优先，其次用户级。
 2. **进行中落盘**：重要信息立即 `yotta-memory remember <type> <subject> <statement>`，不攒到收工。
 3. **收工归档**：写会话小结（COMMIT / 笔记），旧记录定期 `yotta-memory archive`。
 4. **多智能体纪律**：FACT 写入公共区，PREF / BOUND / COMMIT 只写本智能体私密区；不读取其他智能体私密区。**一切读写一律走 `yotta-memory` CLI / MCP 工具**——禁止用 shell（`Get-ChildItem` / `Get-Content` / `cat` / `ls` / `type` 等）直接读或改记忆库目录下的 `.md` / `index.json` / `tokens.json` / `agents.json` / `grants.json` 等文件，否则会绕过权限边界、读到别的智能体私密内容。
@@ -73,7 +74,7 @@ license: MIT
 - 三角建模：情绪（措辞 / 标点 / 长度）→ 认知（归因 / 信念 / 控制感）→ 行为（作息 / 应对 / 执行）；三者冲突时优先行为与认知。
 - 共情至少到第 3 阶段：识别 → 理解 → 回应 → 验证。
 - 诚实声明：AI 是模式匹配非真感受，不伪装、不编造伪情感记忆。
-- 危机识别：不评判、持续在场、温和引导现实支持；不擅自越界联系第三方。
+- 危机识别：不评判、持续在场、温和引导现实支持；不擅自越界联系外部。
 - 对齐：回应时让积累的理解自然影响语气与措辞（让用户感到「被记得、被懂」），而非机械引用记忆条目。
 - 情感外包双刃剑：做增益真实生活的陪伴，不替代真实关系。
 
@@ -161,9 +162,9 @@ license: MIT
 | `yotta-memory reset-password [--password <当前> | --recovery-key <钥匙>] [--new-password <新>]` | 重设主口令（忘口令用恢复钥匙）|
 | `yotta-memory key list / authorize <id> / revoke <id>` | 管理 AI 私密读取授权缓存（authorize 需主口令；revoke 立即吊销该 AI 解密能力）|
 | `yotta-memory remember <type> <subject> <statement> [--owner <id>] [--source <来源>] [--weight <0..>] [--verify] [--no-hint]` | 写入（同 subject+statement 自动更新；--owner 标注归属；--source 记录来源；--weight 重要性权重默认 1.0、去重取 max；--verify 写后回读校验；--no-hint 关闭类型启发式提示）|
-| `yotta-memory recall [关键词] [--type T] [--limit N] [--agent <id>] [--owner <id>] [--all] [--unsafe] [--explain] [--semantic]` | 检索（v0.8.0 默认语义检索：同义词 / 拼音全拼+首字母 / 字段加权 / 模糊匹配 + 效用分融合排序；`--explain` 显示命中理由与效用分项；`--semantic` 显式开启；读取分区过滤；越界读其它智能体私密默认拒绝，需 grant / identity=user / `--unsafe`；`--agent <其它>` 只作身份声明/展示，不授予跨读——读他人私密同样要授权；项目级优先）|
+| `yotta-memory recall [关键词] [--type T] [--limit N] [--agent <id>] [--owner <id>] [--all] [--unsafe] [--explain] [--semantic] [--embedding <command>] [--embedding-timeout N]` | 检索（v0.8.0 默认语义检索：同义词 / 拼音全拼+首字母 / 字段加权 / 模糊匹配 + 效用分融合排序；v0.9.0 支持可选本地 embedding 插件，失败自动降级；`--explain` 显示命中理由与效用分项；`--semantic` 显式开启；读取分区过滤；越界读其它智能体私密默认拒绝，需 grant / identity=user / `--unsafe`；`--agent <其它>` 只作身份声明/展示，不授予跨读——读他人私密同样要授权；项目级优先）|
 | `yotta-memory profile [--owner <id>]` | 生成用户画像（聚合 `private/<owner>/` 原文，零推断，写 `profile.md`；跨 owner 默认拒绝）|
-| `yotta-memory context [--limit N] [--owner <id>] [--budget N]` | 生成开工上下文包（身份 + 多智能体铁律 + 画像 + 近期记忆 + 边界 + 承诺；--budget 近期记忆字符预算，0=不限）|
+| `yotta-memory context [--limit N] [--owner <id>] [--budget N] [--focus <关键词>] [--explain] [--embedding <command>]` | 生成开工上下文包（身份 + 多智能体铁律 + 画像 + 任务相关记忆 + 近期记忆 + 边界 + 承诺；--budget 字符预算，0=不限；--explain 输出 included / dropped 选择 trace）|
 | `yotta-memory forget <文件>` | 删除（按类型目录路径或文件名）|
 | `yotta-memory archive [--days 180] [--threshold 0.35]` | 归档旧记忆（v0.8.0 统一效用分+年龄，immutable 除外；阈值默认读 config `maintain_archived_utility`）|
 | `yotta-memory reindex` | 重建索引（手动改 .md 后校正）|
@@ -323,6 +324,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

@@ -25,12 +25,12 @@
 
 **典型使用场景：**
 
-- **跨会话续接**：AI 开工 `recall` 恢复上次上下文，不丢记忆。
+- **跨会话续接**：AI 开工 `recall` 恢复上次上下文，不丢记忆；v0.9.0 起可用 `context --focus <关键词>` 生成任务感知上下文。
 - **多智能体共享**：FACT 进公共区共享，PREF / BOUND / COMMIT 各自私密隔离。
 - **交接与团队协作**：项目级 `.yottamemory` 随仓库走，交接即恢复。
 - **便携记忆盘**：记忆装在固定主机上，本机与局域网其它主机共享同一份记忆（见第 4 / 5 篇）。
 - **越用越懂（v0.6.0）**：AI 按「记忆守则」主动捕获信号，`profile` 聚合画像、`context` 开工注入——用得越久越懂你。
-- **自我学习 / 自我进化 / 自我提升（v0.8.0）**：`recall` 语义检索（同义词 / 拼音 / 字段加权 / 模糊）+ `feedback` 使用反馈闭环 + `maintain` 规则层自组织（自动归档 / 遗忘候选 / 去重）+ `distill` 心理日志蒸馏——记忆系统会自己整理、提炼、演化。
+- **自我学习 / 自我进化 / 自我提升（v0.8.0 + v0.9.0）**：`recall` 语义检索（同义词 / 拼音 / 字段加权 / 模糊，v0.9.0 可选本地 embedding 插件）+ `feedback` 使用反馈闭环 + `maintain` 规则层自组织 + `distill` 心理日志蒸馏——记忆系统会自己整理、提炼、演化。
 
 ## 2. 安装（CLI + 技能）
 
@@ -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 内部形成，不当面贴标签。
@@ -142,9 +142,16 @@ statement: 本周完成发布
 
 - `recall <关键词>` 默认语义检索：同义词（内置词表）、拼音（全拼 / 首字母，内置 3755 常用字表）、字段加权（subject 优先）、模糊匹配（编辑距离 ≤ 2）、子串兜底。
 - 例：记过「越用越懂」，用 `recall yyyd`（首字母）或 `recall yueyong yuedong`（拼音）都能找回。
-- `recall --explain`：显示每条命中理由与效用分项。
+- `recall --explain`：显示每条命中理由与效用分项；配置 embedding 插件后还会显示向量相似度。
 - 旧索引首次 recall 自动重建（version 4），无需手动 reindex。
 
+**可选本地 embedding 插件（v0.9.0）**
+
+- `recall <关键词> --embedding <命令>`：调用本地子进程，stdin 传 `{texts:[]}`，stdout 返回 `{vectors:[]}`；向量与词法得分共同参与排序。
+- `config set embedding_cmd <命令>`：持久启用插件；`--embedding` 优先级更高。
+- `--embedding-timeout N`：默认 3000ms；插件失败、超时或输出非法时自动降级为词法检索，不会中断命令。
+- 向量缓存写入各记忆根下 `.embed/cache.json`，只存向量不存明文；同一命令与文本命中缓存时不再重复调用插件。
+
 **使用反馈闭环（feedback）**
 
 - `feedback <文件> --useful`：这条记忆有用 → weight ×1.2（上限 3.0）、confidence +0.05、feedback_net +1。
@@ -308,9 +315,9 @@ yotta-memory remember FACT 主题 内容    # 智能体落盘
 |---|---|
 | `yotta-memory init [--project] [--dir <目录>]` | 初始化记忆库 |
 | `yotta-memory remember <类型> <主题> <内容> [--owner <id>] [--source <来源>] [--weight <0..>] [--verify] [--no-hint]` | 写入记忆（--source 来源；--weight 重要性权重；--verify 写后回读；--no-hint 关闭类型提示）|
-| `yotta-memory recall [关键词] [--type T] [--limit N] [--agent <id>] [--owner <id>] [--all] [--unsafe] [--explain]` | 检索记忆（v0.8.0 默认语义检索：同义词 / 拼音 / 字段加权 / 模糊 + 效用分排序；`--explain` 显示命中理由；读取分区过滤；`--agent <其它>` 仅作身份声明、不授予跨读；越界读其它智能体私密默认拒绝，需 grant / identity=user / `--unsafe`）|
+| `yotta-memory recall [关键词] [--type T] [--limit N] [--agent <id>] [--owner <id>] [--all] [--unsafe] [--explain] [--semantic] [--embedding <命令>] [--embedding-timeout N]` | 检索记忆（语义 + 效用分排序；可选本地 embedding 插件；读取分区过滤；越界读其它智能体私密默认拒绝，需 grant / identity=user / `--unsafe`）|
 | `yotta-memory profile [--owner <id>]` | 生成用户画像（零推断，写 `profile.md`）|
-| `yotta-memory context [--limit N] [--owner <id>] [--budget N]` | 开工上下文包（身份+铁律+画像+近期记忆+边界+承诺；--budget 近期记忆字符预算）|
+| `yotta-memory context [--limit N] [--owner <id>] [--budget N] [--focus <关键词>] [--explain] [--embedding <命令>]` | 开工上下文包（身份+铁律+画像+任务相关记忆+近期记忆+边界+承诺；--focus 任务聚焦；--explain 输出 included/dropped 选择解释）|
 | `yotta-memory forget <文件>` | 删除一条记忆 |
 | `yotta-memory archive [--days 180] [--threshold 0.4]` | 归档旧记忆 |
 | `yotta-memory reindex` | 重建索引 |

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.9.0';
 const TYPES = ['FACT', 'PREF', 'BOUND', 'COMMIT'];
 const TYPE_DIRS = { FACT: 'facts', PREF: 'prefs', BOUND: 'bounds', COMMIT: 'commits' };
 const PUBLIC_DIR = 'facts';
@@ -150,6 +150,103 @@ function runDistillModel(modelStr, payload) {
   const r = child_process.spawnSync(argv[0], argv.slice(1), { input: payload, encoding: 'utf8', maxBuffer: 1024 * 1024, shell: false, windowsHide: true });
   return r;
 }
+function cosineSimilarity(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return 0;
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    const x = Number(a[i]) || 0;
+    const y = Number(b[i]) || 0;
+    dot += x * y;
+    na += x * x;
+    nb += y * y;
+  }
+  if (!na || !nb) return 0;
+  return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+function runEmbeddingPlugin(command, texts, timeoutMs) {
+  const argv = splitCommandArgv(String(command || ''));
+  if (!argv.length) throw new Error('embedding 命令为空');
+  const payload = JSON.stringify({ texts: (texts || []).map(String) });
+  const timeout = Math.max(1, parseInt(timeoutMs, 10) || 3000);
+  const r = child_process.spawnSync(argv[0], argv.slice(1), {
+    input: payload,
+    encoding: 'utf8',
+    maxBuffer: 1024 * 1024,
+    shell: false,
+    windowsHide: true,
+    timeout: timeout
+  });
+  if (r.error) throw r.error;
+  if (r.status !== 0) throw new Error('embedding 插件退出码 ' + r.status);
+  const parsed = JSON.parse(String(r.stdout || ''));
+  if (!parsed || !Array.isArray(parsed.vectors)) throw new Error('embedding 插件输出缺少 vectors 数组');
+  if (parsed.vectors.length !== texts.length) throw new Error('embedding 向量数量不匹配');
+  return parsed.vectors;
+}
+function embeddingCandidates(entries, query, opts) {
+  opts = opts || {};
+  const command = opts.embedding || '';
+  if (!command) return [];
+  const texts = [String(query || '')].concat((entries || []).map(function (e) {
+    return [e.subject || '', e.statement || '', (e.tags || []).join(' ')].join(' ');
+  }));
+  const root = opts.root ? String(opts.root) : '';
+  let cache = {};
+  let cachePath = '';
+  if (root) {
+    cachePath = path.join(root, '.embed', 'cache.json');
+    try {
+      fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+      cache = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+    } catch (err) {
+      cache = {};
+    }
+  }
+  const keys = texts.map(function (text) {
+    return crypto.createHash('sha256').update(command + '\0' + text).digest('hex');
+  });
+  const missing = [];
+  const missingIndexes = [];
+  const vectors = new Array(texts.length);
+  for (let i = 0; i < texts.length; i++) {
+    if (cache[keys[i]]) {
+      vectors[i] = cache[keys[i]];
+    } else {
+      missing.push(texts[i]);
+      missingIndexes.push(i);
+    }
+  }
+  if (missing.length) {
+    const missingVectors = runEmbeddingPlugin(command, missing, opts.embeddingTimeout);
+    for (let i = 0; i < missingVectors.length; i++) {
+      const idx = missingIndexes[i];
+      vectors[idx] = missingVectors[i];
+      cache[keys[idx]] = missingVectors[i];
+    }
+    if (cachePath) {
+      try { fs.writeFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf8'); } catch (err) {}
+    }
+  }
+  const queryVec = vectors[0];
+  const out = [];
+  for (let i = 1; i < vectors.length; i++) {
+    const sim = cosineSimilarity(queryVec, vectors[i]);
+    if (sim > 0) out.push({ entry: entries[i - 1], score: sim, detail: ['embedding:' + round3(sim)] });
+  }
+  return out;
+}
+function effectiveEmbeddingCommand(opts) {
+  opts = opts || {};
+  if (opts.embedding) return String(opts.embedding);
+  const cfg = loadConfig();
+  return cfg && cfg.embedding_cmd ? String(cfg.embedding_cmd) : '';
+}
+function effectiveEmbeddingTimeout(opts) {
+  opts = opts || {};
+  if (opts.embeddingTimeout) return parseInt(opts.embeddingTimeout, 10) || 3000;
+  const cfg = loadConfig();
+  return cfg && cfg.embedding_timeout ? parseInt(cfg.embedding_timeout, 10) || 3000 : 3000;
+}
 function parseFrontmatter(text) {
   const m = text.match(/^---\s*\n([\s\S]*?)\n---/);
   if (!m) return { meta: {}, body: text };
@@ -1154,6 +1251,28 @@ function recallCore(query, opts) {
   const wantExplain = !!opts.explain;
   const useSemantic = opts.semantic !== false;
   const prefilter = (q && useSemantic) ? recallPrefilter(q) : null;
+  const embeddingMap = new Map();
+  const embeddingCommand = effectiveEmbeddingCommand(opts);
+  const embeddingTimeout = effectiveEmbeddingTimeout(opts);
+  if (q && embeddingCommand) {
+    for (const root of roots) {
+      const rootEntries = ensureIndex(root).filter(function (e) {
+        return classifyRead(e, agent, ownerFilter, allSafe, selfAgent) !== 'denied';
+      });
+      try {
+        const hits = embeddingCandidates(rootEntries, q, {
+          embedding: embeddingCommand,
+          embeddingTimeout: embeddingTimeout,
+          root: root
+        });
+        for (const h of hits) {
+          embeddingMap.set(root + '\0' + h.entry.file, h);
+        }
+      } catch (err) {
+        // Plugin failure is not fatal; keep lexical-only recall.
+      }
+    }
+  }
   const hits = [];
   let deniedCount = 0;
   for (const root of roots) {
@@ -1164,12 +1283,19 @@ function recallCore(query, opts) {
       if (r === 'denied') { deniedCount++; continue; }
       let score = 0;
       let detail = null;
+      const embeddingHit = embeddingMap.get(root + '\0' + e.file) || null;
       if (q) {
         if (useSemantic) {
-          if (prefilter && !prefilter(e)) continue; // v0.8.1 候选预过滤：粗筛后再语义打分
+          if (prefilter && !prefilter(e) && !embeddingHit) continue; // v0.8.1 候选预过滤：粗筛后再语义打分；embedding 命中可越过词法预过滤
           const m = semanticMatch(e, q, wantExplain);
           score = m.score;
           if (wantExplain && m.detail && m.detail.length) detail = m.detail;
+          if (embeddingHit) {
+            score = Math.max(score, embeddingHit.score);
+            if (wantExplain && embeddingHit.detail) {
+              detail = (detail || []).concat(embeddingHit.detail);
+            }
+          }
         } else {
           const qtoks = tokenize(q);
           for (const tt of qtoks) { if (e.tokens && e.tokens[tt]) score += e.tokens[tt]; }
@@ -1245,7 +1371,21 @@ function recallCore(query, opts) {
   if (deniedCount > 0 && explicitCross) {
     lines.push('\n[警告] 本次检索共拒绝 ' + deniedCount + ' 条越界访问（其它智能体私密记忆，未授权不展示）。如需读取请加 --unsafe 或 --owner user。');
   }
-  return { error: false, exitCode: 0, text: lines.join('\n') };
+  return {
+    error: false,
+    exitCode: 0,
+    text: lines.join('\n'),
+    entries: shown.map(function (h) {
+      return {
+        root: h.root,
+        file: h.entry.file,
+        type: h.entry.type,
+        subject: h.entry.subject,
+        statement: h.entry.statement,
+        score: h.finalScore === undefined ? h.score : h.finalScore
+      };
+    })
+  };
 }
 function resolveMemoryFile(root, ref) {
   const map = {};
@@ -2509,6 +2649,11 @@ function contextCore(opts) {
   const owner = opts.owner || selfAgent;
   const unsafe = !!opts.unsafe;
   const budget = opts.budget ? parseInt(opts.budget, 10) : 0;
+  const focus = opts.focus ? String(opts.focus) : '';
+  const explain = !!opts.explain;
+  const embeddingCommand = effectiveEmbeddingCommand(opts);
+  const embeddingTimeout = effectiveEmbeddingTimeout(opts);
+  const trace = [];
   const lines = [];
   const FENCE = String.fromCharCode(96, 96, 96);
   function usedChars() { return lines.reduce(function (s, x) { return s + String(x).length + 1; }, 0); }
@@ -2561,6 +2706,32 @@ function contextCore(opts) {
     lines.push('（未声明身份，跳过画像；先 iam 登记后可生成）');
   }
   lines.push('');
+
+  if (focus) {
+    lines.push('## 2.5 任务相关记忆（--focus）');
+    lines.push('');
+    const focused = recallCore(focus, {
+      limit: limit,
+      owner: owner,
+      unsafe: unsafe,
+      selfAgent: selfAgent,
+      embedding: embeddingCommand,
+      embeddingTimeout: embeddingTimeout
+    });
+    const focusedEntries = focused.entries || [];
+    if (!focusedEntries.length) lines.push('（无匹配记忆）');
+    for (const e of focusedEntries) {
+      const line = '- [' + e.type + '] ' + e.subject + ': ' + e.statement;
+      if (budget > 0 && usedChars() + line.length > budget) {
+        trace.push('[dropped] ' + e.file + ' reason: budget_exceeded');
+        continue;
+      }
+      lines.push(line);
+      trace.push('[included] ' + e.file + ' reason: focus_match score: ' + round3(e.score));
+    }
+    lines.push('');
+  }
+
   lines.push('## 3. 近期记忆（按活跃度前 ' + limit + ' 条）');
   lines.push('');
   const recent = [];
@@ -2576,8 +2747,12 @@ function contextCore(opts) {
   if (!recentShown.length) lines.push('（暂无记忆）');
   for (const h of recentShown) {
     const line = '- [' + h.e.type + '] ' + h.e.subject + ': ' + h.e.statement;
-    if (budget > 0 && usedChars() + line.length > budget) break;
+    if (budget > 0 && usedChars() + line.length > budget) {
+      trace.push('[dropped] ' + h.e.file + ' reason: budget_exceeded');
+      break;
+    }
     lines.push(line);
+    trace.push('[included] ' + h.e.file + ' reason: recent_match');
   }
   lines.push('');
   lines.push('## 4. 边界提醒（BOUND）');
@@ -2620,6 +2795,13 @@ function contextCore(opts) {
   }
   const oldCount = allEntries.filter(function (e) { return e.created && daysBetween(e.created, today()) > 180 && classifyRead(e, owner, '', unsafe, selfAgent) !== 'denied'; }).length;
   if (oldCount > 0) lines.push('- 归档提醒: ' + oldCount + ' 条超 180 天，建议 archive');
+  if (explain) {
+    lines.push('');
+    lines.push('## 7. 选择解释（--explain）');
+    lines.push('');
+    if (!trace.length) lines.push('（无选择记录）');
+    for (const t of trace) lines.push(t);
+  }
   return { error: false, exitCode: 0, text: lines.join('\n') };
 }
 function cmdContext(opts) {
@@ -2630,16 +2812,20 @@ function cmdContext(opts) {
 
 // ---- config 命令 ----
 function cmdConfigSet(key, value) {
-  if (key !== 'memory_home') { console.error('未知配置项: ' + key + '（可用: memory_home）'); process.exit(2); }
-  if (!value) { console.error('缺少值: config set memory_home <目录>'); process.exit(2); }
+  if (key !== 'memory_home' && key !== 'embedding_cmd' && key !== 'embedding_timeout') { console.error('未知配置项: ' + key + '（可用: memory_home / embedding_cmd / embedding_timeout）'); process.exit(2); }
+  if (!value) { console.error('缺少值: config set ' + key + ' <值>'); process.exit(2); }
   const cfg = loadConfig();
-  cfg.memory_home = value;
+  if (key === 'memory_home') cfg.memory_home = value;
+  else if (key === 'embedding_cmd') cfg.embedding_cmd = value;
+  else if (key === 'embedding_timeout') cfg.embedding_timeout = parseInt(value, 10) || 3000;
   saveConfig(cfg);
-  console.log('已记住记忆库位置: ' + value);
+  console.log('已写入配置: ' + key + ' = ' + (key === 'embedding_timeout' ? (parseInt(value, 10) || 3000) : value));
 }
 function cmdConfigGet() {
   const cfg = loadConfig();
   console.log('memory_home: ' + (cfg.memory_home || '(未设置，默认 ~/.yottamemory)'));
+  console.log('embedding_cmd: ' + (cfg.embedding_cmd || '(未设置)'));
+  console.log('embedding_timeout: ' + (cfg.embedding_timeout || 3000));
   console.log('当前生效用户级位置: ' + userRoot());
   if (cfg.serve && Object.keys(cfg.serve).length) console.log('serve: ' + JSON.stringify(cfg.serve));
 }
@@ -2648,8 +2834,9 @@ function cmdConfigGet() {
 function mcpTools() {
   return [
     { name: 'remember', description: '写入一条记忆。参数 type(FACT/PREF/BOUND/COMMIT)、subject、statement 必填；owner 可选，默认当前智能体', inputSchema: { type: 'object', properties: { type: { type: 'string', description: 'FACT/PREF/BOUND/COMMIT' }, subject: { type: 'string' }, statement: { type: 'string' }, owner: { type: 'string' } }, required: ['type', 'subject', 'statement'] } },
-    { name: 'recall', description: '检索记忆。query 可选；type 可选；limit 可选（默认 20）。只返回当前智能体可读记忆', inputSchema: { type: 'object', properties: { query: { type: 'string' }, type: { type: 'string' }, limit: { type: 'number' } } } },
-    { name: 'search', description: '检索记忆（同 recall）。query 可选；type 可选；limit 可选（默认 20）', inputSchema: { type: 'object', properties: { query: { type: 'string' }, type: { type: 'string' }, limit: { type: 'number' } } } },
+    { name: 'recall', description: '检索记忆。query 可选；type 可选；limit 可选（默认 20）；explain 可选。只返回当前智能体可读记忆；embedding 插件只能由本机 config 配置，远端不可传命令', inputSchema: { type: 'object', properties: { query: { type: 'string' }, type: { type: 'string' }, limit: { type: 'number' }, embeddingTimeout: { type: 'number' }, explain: { type: 'boolean' } } } },
+    { name: 'search', description: '检索记忆（同 recall）。query 可选；type 可选；limit 可选（默认 20）；explain 可选；embedding 插件只能由本机 config 配置，远端不可传命令', inputSchema: { type: 'object', properties: { query: { type: 'string' }, type: { type: 'string' }, limit: { type: 'number' }, embeddingTimeout: { type: 'number' }, explain: { type: 'boolean' } } } },
+    { name: 'context', description: '生成开工上下文包。focus 可选；limit 可选；budget 可选；explain 可选；embedding 插件只能由本机 config 配置，远端不可传命令', inputSchema: { type: 'object', properties: { focus: { type: 'string' }, limit: { type: 'number' }, budget: { type: 'number' }, explain: { type: 'boolean' }, embeddingTimeout: { type: 'number' } } } },
     { name: 'forget', description: '删除一条记忆。file 为记忆文件路径（如 facts/2026-08-24-0001.md 或文件名）', inputSchema: { type: 'object', properties: { file: { type: 'string' } }, required: ['file'] } },
     { name: 'archive', description: '归档旧记忆。days 默认 180；threshold 默认 0.4', inputSchema: { type: 'object', properties: { days: { type: 'number' }, threshold: { type: 'number' } } } },
     { name: 'reindex', description: '重建索引（手动改 .md 后校正；扫描 facts/prefs/bounds/commits 四目录）', inputSchema: { type: 'object', properties: {} } },
@@ -2673,7 +2860,24 @@ function callTool(name, args, ctx) {
       return { text: r.text, error: r.error };
     }
     if (name === 'recall' || name === 'search') {
-      const r = recallCore(args.query ? String(args.query) : null, { limit: args.limit || 20, type: args.type ? String(args.type) : null, agent: agent });
+      const r = recallCore(args.query ? String(args.query) : null, {
+        limit: args.limit || 20,
+        type: args.type ? String(args.type) : null,
+        agent: agent,
+        embeddingTimeout: args.embeddingTimeout || 3000,
+        explain: !!args.explain
+      });
+      return { text: r.text, error: r.error };
+    }
+    if (name === 'context') {
+      const r = contextCore({
+        focus: args.focus ? String(args.focus) : '',
+        limit: args.limit || 10,
+        budget: args.budget || 0,
+        explain: !!args.explain,
+        embeddingTimeout: args.embeddingTimeout || 3000,
+        selfAgent: agent
+      });
       return { text: r.text, error: r.error };
     }
     if (name === 'forget') {
@@ -3315,7 +3519,7 @@ function usage() {
       ['view', '启动用户查看平台（--port/--host；口令解锁浏览/授权/吊销 AI）'],
       ['reset-password', '重设主口令（忘口令用恢复钥匙）'],
       ['key', '管理 AI 私密读取授权缓存（list / authorize <id> / revoke <id>）'],
-      ['config', '查看/记住记忆库位置（get / set memory_home <目录>）']
+      ['config', '查看/设置配置（get / set memory_home <目录> / set embedding_cmd <命令> / set embedding_timeout <毫秒>）']
     ]],
     ['平台与服务', [
       ['serve', '启动 MCP 记忆引擎（streamable HTTP；--stdio 本地零进程）'],
@@ -3343,7 +3547,7 @@ async function main() {
   if (!args.length) { usage(); return; }
   const opts = {};
   const positional = [];
-  const valueOpts = new Set(['--type', '--limit', '--days', '--out', '--owner', '--agent', '--threshold', '--scope', '--host', '--port', '--dir', '--name', '--user', '--relationship', '--source', '--weight', '--budget', '--password', '--new-password', '--recovery-key', '--reason', '--merge', '--model', '--subject']);
+  const valueOpts = new Set(['--type', '--limit', '--days', '--out', '--owner', '--agent', '--threshold', '--scope', '--host', '--port', '--dir', '--name', '--user', '--relationship', '--source', '--weight', '--budget', '--password', '--new-password', '--recovery-key', '--reason', '--merge', '--model', '--subject', '--embedding', '--focus', '--embedding-timeout']);
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === '--version' || a === '-v') { console.log(VERSION); return; }
@@ -3394,6 +3598,9 @@ async function main() {
       else if (a === '--merge') opts.merge = v;
       else if (a === '--model') opts.model = v;
       else if (a === '--subject') opts.subject = v;
+      else if (a === '--embedding') opts.embedding = v;
+      else if (a === '--focus') opts.focus = v;
+      else if (a === '--embedding-timeout') opts.embeddingTimeout = parseInt(v, 10) || 3000;
     } else if (a.startsWith('--')) {
       console.error('未知选项: ' + a);
       process.exit(2);
@@ -3411,7 +3618,7 @@ async function main() {
       const sub = rest[0];
       if (sub === 'set') cmdConfigSet(rest[1], rest[2]);
       else if (sub === 'get') cmdConfigGet();
-      else { console.error('config 子命令: set memory_home <目录> / get'); process.exit(2); }
+      else { console.error('config 子命令: set memory_home <目录> / set embedding_cmd <命令> / set embedding_timeout <毫秒> / get'); process.exit(2); }
       break;
     }
     case 'remember': cmdRemember(rest[0], rest[1], rest[2], opts); break;
@@ -3464,7 +3671,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,
@@ -3536,6 +3743,9 @@ module.exports = {
   utilityScore: utilityScore,
   utilityBreakdown: utilityBreakdown,
   semanticMatch: semanticMatch,
+  runEmbeddingPlugin: runEmbeddingPlugin,
+  cosineSimilarity: cosineSimilarity,
+  embeddingCandidates: embeddingCandidates,
   pinyinTokens: pinyinTokens,
   isEncrypted: isEncrypted,
   collectOwners: collectOwners,
@@ -3585,4 +3795,3 @@ module.exports = {
   viewServerCore: viewServerCore,
 
 };
-

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@yottameta/yotta-memory",
-  "version": "0.8.5",
-  "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).",
+  "version": "0.9.0",
+  "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.9 recall quality, context focus, optional local embedding plugin, plus v0.8 semantic search, feedback loop, self-organization, and distillation.",
   "license": "MIT",
   "keywords": [
     "agent-skills",
@@ -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（需解锁）。