docs(memory): refresh user manual to align with anolisa-design structure

[shiloong]

Description

Restructure zh/en manuals to match ANOLISA-design user-guide section order (installation, integration, MCP tool set, core features, configuration, use cases). Lead with anolisa install/adapter enable/doctor as primary entry; keep RPM/source/make as advanced paths. Update MCP tool count to 34 with corrected tier groupings and new sovereignty/task/import-export tools, and map all config keys, env vars, install paths, and profiles to current code baseline.

Related Issue

no-issue: agent-memory documentation refresh

Scope

• docs

Checklist

• Code follows project style
• Rebased on latest main

[Forrest-ly]

Code Review — PR #1179

PR 将中英文用户手册重构为 ANOLISA-design user-guide 章节顺序（安装 → 集成 → 工具集 → 核心特性 → 配置 → 场景），新增 Sovereignty/导入导出工具组，压缩冗长段落。净删除 477 行。

---

1. 工具数 34 vs 实际 37，缺少 3 个已合并工具 — High

profile_test.rs 当前 TOTAL_TOOLS = 37，mcp_integration_test.rs 列出 37 个工具。文档声称 34 个，缺少：

缺失工具	来源 PR	说明
memory_summary	#1124	记忆仓统计概览
memory_session_context	#1132	会话启动上下文注入
mem_dream	#1125	用户画像合成

这 3 个工具已合并到 main，应加入文档工具表并把工具数改为 37。

2. Embedding 环境变量名错误 — High

user_manual.md 与 user_manual.zh.md 的 "Hybrid vector search / 混合向量搜索" 段落写的是：

EMBEDDING_PROVIDER=openai

代码（config.rs:486）实际为 MEMORY_EMBEDDING_BACKEND。同一文档的环境变量表中也正确写了 MEMORY_EMBEDDING_BACKEND — 文档内部自相矛盾。中英文均需修正。

3. MEMORY_PROFILE 默认值错误 — High

环境变量表声称默认值为 basic：

| MEMORY_PROFILE | profile (basic/advanced/expert) | basic |

config.rs 中 default_profile() 返回 Profile::Advanced，且同一文档的 Profile 描述也写了 "advanced (default)"。应改为 advanced。

4. Expert profile 隐藏范围与文档描述不一致 — High

文档声称 Expert 只隐藏 Tier B 的 3 个工具：

expert — hides Tier B (memory_search, memory_observe, memory_get_context)

但 config.rs:298-306 显示 Expert 实际隐藏 6 个工具（TIER_B_COUNT = 6）：

let tier_b = matches!(
    tool_name,
    "memory_search"
        | "memory_observe"
        | "memory_get_context"
        | "mem_consolidate"       // ← 文档归类 Tier C
        | "memory_forget"         // ← 文档归类 Sovereignty
        | "memory_consent"        // ← 文档归类 Sovereignty
);

两个问题叠加：
- Expert 描述漏列 mem_consolidate、memory_forget、memory_consent
- 文档 Tier B 分组（含 memory_sessions/memory_timeline/mem_index_refresh）与代码 expert 隐藏集（含 mem_consolidate/memory_forget/memory_consent）交集只有 3 个

建议：明确列出 expert 隐藏的全部 6 个工具名，或调整 tier 分组以反映代码中的实际边界。

5. SDK 示例过度截断 — Low

- Rust：call_tool 调用被删除，只剩连接建立代码
- Python / TypeScript：result.content[0].text 等结果访问代码被删

开发者接入时需要知道怎么发起调用和读取返回值，建议保留最小完整示例。

6. 威胁模型段落被删除 — Low

旧版包含精简威胁模型（"服务端把 Agent 视为不可信进程…openat2 RESOLVE_BENEATH…"），对安全审查有参考价值。建议保留或移至独立安全文档。

---
总结

4 个事实性错误需修复：

1. 工具数 34 → 37，补 memory_summary / memory_session_context / mem_dream
2. EMBEDDING_PROVIDER → MEMORY_EMBEDDING_BACKEND（中英文）
3. 默认 profile basic → advanced（中英文环境变量表）
4. Expert 隐藏 6 个工具而非 3 个，隐藏集与文档 Tier B 分组不匹配

修复事实性错误后可合并。

[shiloong]

Review 修复回复

#1 工具数 34 → 37 — ✅ 已修复

工具数改为 37，工具表新增 memory_summary、memory_session_context、mem_dream 三个工具（中英文均更新）。Sovereignty & import/export 分组从 10 改为 13。

#2 EMBEDDING_PROVIDER → MEMORY_EMBEDDING_BACKEND — ✅ 已修复

中英文均已修正为 MEMORY_EMBEDDING_BACKEND，与环境变量表一致。

#3 MEMORY_PROFILE 默认值 basic → advanced — ✅ 已修复

中英文环境变量表均已改为 advanced，与 config.rs 的 default_profile() 和文档 Profile 描述一致。

#4 Expert 隐藏范围 — ✅ 已修复

中英文 expert 描述均已列出全部 6 个隐藏工具：memory_search、memory_observe、memory_get_context、mem_consolidate、memory_forget、memory_consent。

#5 SDK 示例截断 — ⚠️ 后续补充

当前示例聚焦连接建立，调用示例可后续补充完整 call_tool + result 读取。

#6 威胁模型段落 — ⚠️ 后续补充

安全模型描述可移至独立安全文档，本 PR 聚焦文档结构重构。

CI: success ✅ MERGEABLE ✅

[Forrest-ly]

---

PR #1179 Re-review — docs(memory): refresh user manual to align with anolisa-design structure

对照开发者修复回复和最新 diff，逐项验证。

---

已验证修复 ✅

#1 工具数 34 → 37 — ✅ 已修复

• en ## MCP tool set (37 tools) ✅
• zh ## MCP 工具集（37 个） ✅
• memory_summary、memory_session_context、mem_dream 已加入"Sovereignty & import/export (13)"表 ✅
• Tier 合计 11 + 6 + 7 + 13 = 37 ✅
• Profile 描述已改为 "all 37 tools" ✅

#2 EMBEDDING_PROVIDER → MEMORY_EMBEDDING_BACKEND — ✅ 已修复

• en "Hybrid vector search" 改为 MEMORY_EMBEDDING_BACKEND=openai / ollama ✅
• zh "混合向量搜索" 同步修正 ✅
• 与环境变量表一致 ✅

#3 MEMORY_PROFILE 默认值 basic → advanced — ✅ 已修复

• en/zh 环境变量表均改为 advanced ✅
• 与 config.rs:default_profile() 和 Profile 描述一致 ✅

#4 Expert 隐藏范围 — ✅ 已修复

• en: expert — hides Tier B (memory_search, memory_observe, memory_get_context, mem_consolidate, memory_forget, memory_consent) ✅ 列出全部 6 个
• zh: 同步更新 ✅

---

残留问题

#5 英文文档 mcp-server.json 工具数仍为 34 — Low（diff line 140）

/usr/share/anolisa/mcp-servers/agent-memory.json lists all 34 tool names

中文文档已正确改为 37（diff line 1331），英文文档此处遗漏。应改为 37 以保持中英文一致。

（注：mcp-server.json 文件实际只有 31 条，缺 memory_sessions、memory_timeline、mem_index_refresh、memory_summary、memory_session_context、mem_dream 共 6 个，但那是代码侧的问题，不在本 PR 范围。）

#6 memory_summary / memory_session_context / mem_dream 归类到 Sovereignty — Nit

这 3 个工具（记忆仓统计、会话上下文注入、用户画像合成）与"主权与导入导出"语义不太匹配。若后续增设 "Tier B — 结构化 API" 或 "分析与合成" 分组会更清晰，但不阻塞合并。

---

总结

上轮 4 个 High 优先级事实性错误已全部修复。残留一处英文文档中 mcp-server.json 工具数遗漏（34 → 37），属 typo 级别。修正后可合并。

[shiloong]

Re-review 回复

#5 英文 mcp-server.json 工具数 34 → 37 — ✅ 已修复

user_manual.md line 85 已改为 "lists all 37 tool names"，与中文文档一致。

#6 memory_summary / memory_session_context / mem_dream 归类 — ⚠️ Nit

同意语义不完全匹配。后续可在工具表增设"分析与合成"分组，调整归类。不阻塞合并。

CI: success ✅ MERGEABLE ✅

[Forrest-ly]

LGTM