smart_brain 0.1.2 → 0.2.0

data/MEMPAL_GUIDE.md

@@ -0,0 +1,1074 @@
+# mempal 完整使用指南
+
+> 版本：v0.9.0 | 2026-07-09
+> `cargo install mempal` — 单二进制项目记忆工具，让任何 coding agent 在 10 秒内带出处找回历史决策。
+
+---
+
+## 目录
+
+1. [核心概念](#1-核心概念)
+2. [安装](#2-安装)
+3. [配置](#3-配置)
+4. [CLI 命令速查表](#4-cli-命令速查表)
+5. [快速入门 5 分钟](#5-快速入门-5-分钟)
+6. [核心 CLI 工作流](#6-核心-cli-工作流)
+7. [知识生命周期（Knowledge Lifecycle）](#7-知识生命周期knowledge-lifecycle)
+8. [Phase-2 Knowledge Card](#8-phase-2-knowledge-card)
+9. [Phase-3 自进化（Self-Evolution）](#9-phase-3-自进化self-evolution)
+10. [MCP Server 与工具](#10-mcp-server-与工具)
+11. [多 Agent 协作（Cowork）](#11-多-agent-协作cowork)
+12. [Agent Diary](#12-agent-diary)
+13. [知识图谱（Knowledge Graph）](#13-知识图谱knowledge-graph)
+14. [AAAK 输出格式化](#14-aaak-输出格式化)
+15. [事实核查（Fact Check）](#15-事实核查fact-check)
+16. [Auto-Dream 集成](#16-auto-dream-集成)
+17. [开发命令](#17-开发命令)
+18. [MEMORY_PROTOCOL](#18-memory_protocol)
+19. [FAQ](#19-faq)
+
+---
+
+## 1. 核心概念
+
+在 mempal 中有四个核心名词：
+
+- **wing**：顶级作用域，通常是一个项目或知识域（如 `mempal`、`myapp`）
+- **room**：wing 内的子作用域，由目录结构推断或通过 taxonomy 编辑
+- **drawer**：一条存储的记忆项或文本块
+- **source_file**：drawer 来源文件（相对路径，保持引用稳定）
+
+### 记忆分层（Mind Model）
+
+| Tier | 含义 | 说明 |
+|------|------|------|
+| `dao_tian` | 天道 | 最高层，不可变的根本规律/原则（默认注入 budget=1） |
+| `dao_ren` | 人道 | 经验规则、最佳实践、架构决策 |
+| `shu` | 术 | 特定工具/库/框架的使用技巧 |
+| `qi` | 器 | 具体代码示例、配置片段 |
+| `evidence` | 证据 | 原始记忆，未经提炼的观察记录 |
+
+### 锚点（Anchor）
+
+记忆的作用范围：`worktree` → `repo` → `global`
+
+---
+
+## 2. 安装
+
+```bash
+# 基础安装
+cargo install mempal --version 0.9.0 --locked
+
+# 带 REST API 支持
+cargo install mempal --version 0.9.0 --locked --features rest
+
+# 开发模式
+cargo run -- --help
+cargo run --features rest -- serve --help
+```
+
+数据全部存储在 `~/.mempal/palace.db`（SQLite + sqlite-vec 单一文件）。
+
+---
+
+## 3. 配置
+
+配置文件路径：`~/.mempal/config.toml`
+
+### 默认配置（model2vec 后端）
+
+```toml
+db_path = "~/.mempal/palace.db"
+
+[embed]
+backend = "model2vec"
+# model = "minishlab/potion-multilingual-128M"  # 默认多语言模型，256 维
+```
+
+### ONNX 后端
+
+```toml
+[embed]
+backend = "onnx"
+```
+
+### 外部 API 后端（如 Ollama）
+
+```toml
+[embed]
+backend = "api"
+api_endpoint = "http://localhost:11434/api/embeddings"
+api_model = "nomic-embed-text"
+dimensions = 768
+```
+
+### Feature Flag
+
+| Feature | 作用 |
+|---------|------|
+| `model2vec`（默认） | model2vec-rs 本地嵌入，零原生依赖 |
+| `onnx` | ONNX Runtime，更高精度 |
+| `rest` | 启用 REST API 服务器 |
+
+---
+
+## 4. CLI 命令速查表
+
+### 4.1 基础操作
+
+| 命令 | 用途 |
+|------|------|
+| `mempal status` | 显示 schema 版本、drawer 数量、triple 数、wing/room 分布 |
+| `mempal doctor` | 诊断 binary/PATH/schema 兼容性 |
+| `mempal release-readiness` | 检查发布准备状态（package/docs/spec/runbook 等） |
+
+### 4.2 项目初始化与导入
+
+| 命令 | 用途 |
+|------|------|
+| `mempal init <DIR> [--dry-run] [--ignore-file PATH] [--no-gitignore] [--no-mempalignore]` | 推断 wing 名，生成初始 taxonomy rooms |
+| `mempal ingest --wing <WING> <DIR> [--dry-run] [--room ROOM] [--format FORMAT] [--no-strip-noise] [--diary-rollup]` | 分块、嵌入、存储整个项目目录树 |
+| `mempal ingest <FILE> --wing <WING>` | 导入单文件到指定 wing |
+
+**忽略规则**：默认尊重 `.gitignore` 和 `.mempalignore`，可禁用 `--no-gitignore` / `--no-mempalignore`，用 `--ignore-file PATH` 添加自定义忽略文件。`.git/`、`target/`、`node_modules/` 始终硬跳过。
+
+**支持的格式**（自动检测）：
+- Claude Code JSONL
+- ChatGPT JSON
+- Codex CLI JSONL
+- Slack DM JSON
+- 纯文本（fallback）
+
+### 4.3 搜索与上下文
+
+| 命令 | 用途 |
+|------|------|
+| `mempal search <QUERY> [--wing W] [--room R] [--top-k N] [--json] [--memory-kind evidence\|knowledge] [--field F] [--tier T] [--status S] [--anchor-kind K] [--with-neighbors]` | 混合搜索（BM25 + 向量 + RRF）+ tunnel hints |
+| `mempal context <QUERY> [--field F] [--domain D] [--cwd DIR] [--include-evidence] [--include-cards] [--max-items N] [--dao-tian-limit N] [--format json]` | 按 `dao_tian → dao_ren → shu → qi` 组装 mind-model context；默认 `dao_tian_limit=1` |
+| `mempal brief <QUERY> [--field F] [--domain D] [--cwd DIR] [--max-items N]` | 生成确定性 citation-first 认知要点（summary/key facts/evidence/cards/uncertainty/next actions） |
+| `mempal wake-up [--format aaak]` | L0/L1 重要性排序唤醒刷新 |
+
+### 4.4 跨项目管理
+
+| 命令 | 用途 |
+|------|------|
+| `mempal projects [--format json]` | 列出所有已知项目（wing + worktree + 计数 + 最近活动） |
+| `mempal resume <FUZZY> [--format json] [--evidence-limit N] [--candidate-limit N]` | 模糊匹配项目名并返回路径 + 最近决策 + 下一步 |
+
+### 4.5 知识图谱（KG）
+
+| 命令 | 用途 |
+|------|------|
+| `mempal kg add <Subject> <Predicate> <Object> [--source-drawer ID]` | 添加三元组 |
+| `mempal kg query [--subject S] [--predicate P] [--object O] [--all]` | 查询三元组 |
+| `mempal kg timeline <ENTITY>` | 某实体的时间线视图 |
+| `mempal kg stats` | KG 统计 |
+| `mempal kg list` | 列出所有三元组 |
+
+### 4.6 知识生命周期（Stage-1）
+
+| 命令 | 用途 |
+|------|------|
+| `mempal knowledge policy [--format json]` | 查看 promotion 阈值表 |
+| `mempal knowledge gate <ID> [--target-status S] [--reviewer R] [--format json]` | 只读评估 knowledge drawer 是否满足 promotion 门槛 |
+| `mempal knowledge distill --statement S --content C --tier dao_ren\|qi --supporting-ref IDs [--domain D] [--field F] [--dry-run]` | 从 evidence refs 创建 candidate knowledge drawer |
+| `mempal knowledge promote <ID> --status promoted --verification-ref IDs --reason R [--reviewer R]` | gate-enforced 提升 knowledge drawer |
+| `mempal knowledge demote <ID> --status demoted --evidence-ref IDs --reason R --reason-type contradicted\|obsolete\|superseded` | 降级/退役 knowledge drawer |
+| `mempal knowledge publish-anchor <ID> --to repo\|global --reason R [--target-anchor-id ID] [--cwd DIR] [--reviewer R]` | 显式 outward anchor publication（worktree→repo→global） |
+
+### 4.7 Knowledge Card（Phase-2）
+
+| 命令 | 用途 |
+|------|------|
+| `mempal knowledge-card create --statement S --content C --tier T [--id ID] [--status S] [--domain D] [--field F] [--cwd DIR]` | 创建 knowledge card |
+| `mempal knowledge-card get <CARD_ID>` | 获取单个 card |
+| `mempal knowledge-card list [--tier T] [--status S] [--domain D] [--field F] [--anchor-kind K] [--anchor-id ID]` | 列出 cards |
+| `mempal knowledge-card retrieve <QUERY> [--domain D] [--field F] [--cwd DIR] [--top-k N] [--evidence-top-k N]` | 通过 linked evidence 检索 cards |
+| `mempal knowledge-card link <CARD_ID> <EVIDENCE_DRAWER_ID> --role supports\|contradicts\|teaches [--note N]` | 链接 evidence 到 card |
+| `mempal knowledge-card event <CARD_ID> --type TYPE --reason R [--from-status S] [--to-status S] [--actor A]` | 追加 lifecycle event |
+| `mempal knowledge-card events <CARD_ID>` | 查看 card 的 events 历史 |
+| `mempal knowledge-card gate <CARD_ID> [--target-status S] [--reviewer R]` | card promotion readiness 评估 |
+| `mempal knowledge-card promote <CARD_ID> --status S --verification-ref IDs --reason R [--reviewer R] [--allow-counterexamples] [--enforce-gate\|--no-enforce-gate]` | gate-enforced card promotion |
+| `mempal knowledge-card demote <CARD_ID> --status S --evidence-ref IDs --reason R --reason-type TYPE` | evidence-backed card demotion |
+| `mempal knowledge-card backfill-plan [--tier T] [--status S] [--domain D] [--field F]` | Stage-1 drawer → Phase-2 card 回填预览（dry-run） |
+| `mempal knowledge-card backfill-apply [--tier T] [--status S] [--domain D] [--field F] [--execute]` | 显式执行回填（默认 dry-run，加 `--execute` 写入） |
+
+### 4.8 Phase-3 自进化
+
+#### 4.8.1 Runtime Adoption Evidence
+
+| 命令 | 用途 |
+|------|------|
+| `mempal phase3 adoption guidance` | 查看 recording 语义指南 |
+| `mempal phase3 adoption instrumentation-policy` | 查看只读 instrumentation opt-in 边界 |
+| `mempal phase3 adoption prepare-record --track T --signal S --feature F [--query Q] [--context-hash H] [--card-id ID] [--note N]` | 只读生成 record 命令与 payload |
+| `mempal phase3 adoption capture --surface S --outcome O --track T --signal S --feature F [--query Q] [--card-id ID] [--note N] [--execute]` | 显式 capture surface/outcome → checked runtime adoption record |
+| `mempal phase3 adoption check-record --track T --signal S --feature F [--query Q] [--card-id ID] [--metadata-json JSON]` | 只读检查 record 质量 |
+| `mempal phase3 adoption record-checked --track T --signal S --feature F [--query Q] [--card-id ID] [--allow-warnings]` | 质量门控写入 runtime adoption evidence |
+| `mempal phase3 adoption wrap --track T --signal S --feature F [--execute] [--allow-warnings] <COMMAND>` | 包裹一次 child command，自动 capture adoption evidence |
+| `mempal phase3 adoption record --track T --signal S --feature F [--query Q] [--card-id ID] [--note N] [--metadata-json JSON]` | 直接写入 runtime adoption event |
+| `mempal phase3 adoption list [--track T] [--feature F] [--limit N]` | 列出 adoption events |
+| `mempal phase3 adoption stats [--track T] [--feature F]` | 按 track+feature 汇总 adoption 统计 |
+| `mempal phase3 adoption review [--track T] [--feature F] [--signal S] [--limit N]` | 只读汇总 adoption evidence 审查报告 |
+| `mempal phase3 adoption analytics` | 按 track+feature 汇总 runtime adoption analytics |
+
+#### 4.8.2 Card Context Default
+
+| 命令 | 用途 |
+|------|------|
+| `mempal phase3 gate card-context` | 只读检查 card context 默认开启条件 |
+| `mempal phase3 readiness card-context` | 只读判断 `include_cards` 是否具备未来默认开启资格 |
+| `mempal phase3 default-proposal card-context --rollback-criterion C1 [--rollback-criterion C2 ...]` | 只读生成默认开启提案，不改默认值 |
+| `mempal phase3 default-control card-context --enable [--rollback-criterion C]` | proposal-gated 启用 card context 默认 |
+| `mempal phase3 default-control card-context --disable [--rollback-criterion C]` | 可逆禁用 card context 默认 |
+| `mempal phase3 rollback-control card-context [--execute]` | 将 rollback evidence 转为可执行的默认关闭策略 |
+
+#### 4.8.3 Evaluator Advisory
+
+| 命令 | 用途 |
+|------|------|
+| `mempal phase3 evaluator advise --evaluator-id ID --subject-kind KIND --subject-id ID --proposed-action ACTION --evidence-ref IDs [--counterexample-ref IDs] [--risk-note NOTES] [--note N]` | advisory-only 评估建议，不具备 lifecycle authority |
+
+#### 4.8.4 Research Adapter
+
+| 命令 | 用途 |
+|------|------|
+| `mempal phase3 research-validate-plan <PATH>` | 验证外部 research report contract |
+| `mempal phase3 research-ingest-plan <PATH> [--execute]` | 把 research findings 写入 evidence（默认 dry-run） |
+
+### 4.9 Cowork 多 Agent 协作
+
+#### 4.9.1 基础 Cowork
+
+| 命令 | 用途 |
+|------|------|
+| `mempal cowork-drain --target claude\|codex --cwd DIR [--format plain\|codex-hook-json]` | 排空 inbox 消息（用于 hook 自动交付） |
+| `mempal cowork-drain --target claude\|codex --cwd-source stdin-json [--format codex-hook-json]` | Codex 侧通过 stdin JSON 获取 cwd 的 drain 方式 |
+| `mempal cowork-status --cwd DIR` | 查看 inbox 状态（只读，不排空） |
+| `mempal cowork-runbook` | 打印多 agent 协作操作手册 |
+| `mempal cowork-install-hooks [--global-codex]` | 安装 Claude+Codex UserPromptSubmit hooks |
+
+#### 4.9.2 Multi-Agent Bus
+
+| 命令 | 用途 |
+|------|------|
+| `mempal cowork-register --agent-id ID --tool claude\|codex --cwd DIR [--transport inbox\|tmux] [--tmux-target TARGET]` | 注册 concrete agent 实例 |
+| `mempal cowork-send --from A --to B --cwd DIR --message M [--thread-id TID] [--channel CH]` | 向一个 agent 发送消息 |
+| `mempal cowork-broadcast --from A --to B1 --to B2 --cwd DIR --message M [--thread-id TID] [--channel CH]` | 向多个 agent 广播消息 |
+| `mempal cowork-agent-drain --agent-id ID --cwd DIR [--format plain\|codex-hook-json]` | 排空特定 agent 的 bus inbox |
+| `mempal cowork-agents --cwd DIR [--now ISO]` | 列出已注册 agent（含 presence 状态） |
+| `mempal cowork-events --cwd DIR [--limit N]` | 回放 append-only bus event log |
+| `mempal cowork-ack --agent-id ID --cwd DIR --message-id MID` | 确认一条 delivery 消息 |
+| `mempal cowork-deliveries --agent-id ID --cwd DIR [--pending\|--all]` | 查看 delivery 状态 |
+| `mempal cowork-channel-set --cwd DIR --channel NAME --agent-id ID [--agent-id ID2 ...] [--remove\|--add]` | 管理 channel membership |
+| `mempal cowork-channels --cwd DIR` | 列出所有 channels |
+| `mempal cowork-channel-send --from A --cwd DIR --channel NAME --message M [--thread-id TID]` | 向 channel 所有成员发送 |
+| `mempal cowork-tmux-peek --agent-id ID --cwd DIR [--lines N]` | tmux live pane 只读捕获 |
+| `mempal cowork-heartbeat --agent-id ID --cwd DIR` | 更新 agent 心跳（presence） |
+| `mempal cowork-peek --tool claude\|codex --cwd DIR [--limit N] [--since ISO] [--format json]` | 读 partner agent 的 LIVE session（无 tmux） |
+| `mempal cowork-doctor --cwd DIR [--now ISO] [--probe-tmux]` | 只读诊断 registry/presence/deliveries/sessions/channels |
+| `mempal cowork-session-create --cwd DIR --session-id ID --title T [--goal G] --agent A1 --agent A2 [--channel C] [--thread-id TID]` | 创建 team session |
+| `mempal cowork-sessions --cwd DIR` | 列出 team sessions |
+| `mempal cowork-session-status --cwd DIR --session-id ID --status active\|paused\|closed` | 更新 session 状态 |
+| `mempal cowork-session-close --cwd DIR --session-id ID [--capture] [--execute]` | 关闭 session，可选 capture handoff |
+| `mempal cowork-handoff --cwd DIR [--thread-id TID] [--channel CH] [--session-id SID] [--limit N]` | 生成 multi-agent handoff summary |
+| `mempal cowork-capture --cwd DIR [--summary-source S] [--wing W] [--room R] [--thread-id TID] [--session-id SID] [--note N] [--execute]` | 显式 capture cowork handoff → evidence |
+
+### 4.10 维护命令
+
+| 命令 | 用途 |
+|------|------|
+| `mempal maintenance-runbook` | 打印维护操作手册 |
+| `mempal maintenance guided-run` | 只读输出 dream/maintenance 推荐命令与状态计数 |
+| `mempal delete <DRAWER_ID>` | 软删除（可逆直到 purge） |
+| `mempal purge [--before ISO]` | 永久移除软删除的 drawers |
+| `mempal reindex [--stale] [--force] [--dry-run]` | 切换模型/维度后重新嵌入 |
+| `mempal compress <TEXT>` | 将任意文本格式化为 AAAK |
+| `mempal taxonomy list` | 查看当前路由关键词 |
+| `mempal taxonomy edit <WING> <ROOM> --keywords K1,K2` | 调整路由行为 |
+| `mempal field-taxonomy [--format json]` | 查看 recommended field 值 |
+| `mempal tunnels` | 发现跨 wing 共享 room |
+| `mempal tunnels add --left W1 --right W2 --label L` | 显式添加跨 wing 链接 |
+| `mempal tunnels delete <ID>` | 删除 tunnel |
+| `mempal tunnels follow --from W [--hops N]` | 沿 tunnel 链遍历 |
+
+### 4.11 服务与基准测试
+
+| 命令 | 用途 |
+|------|------|
+| `mempal serve --mcp` | 通过 stdio 运行 MCP 服务器 |
+| `mempal fact-check [PATH\|-] [--wing W] [--room R] [--now ISO]` | 离线矛盾检测（读文件或 stdin） |
+| `mempal bench longmemeval <DATA_FILE> [--mode raw\|aaak\|rooms] [--granularity session\|turn] [--limit N] [--top-k N] [--out FILE]` | 运行 LongMemEval 检索基准测试 |
+
+---
+
+## 5. 快速入门 5 分钟
+
+### 5.1 推断并写入 taxonomy
+
+```bash
+# 预览
+mempal init ~/code/myapp --dry-run
+
+# 写入
+mempal init ~/code/myapp
+```
+
+### 5.2 预览导入
+
+```bash
+mempal ingest ~/code/myapp --wing myapp --dry-run
+```
+
+### 5.3 导入项目
+
+```bash
+mempal ingest ~/code/myapp --wing myapp
+```
+
+### 5.4 搜索
+
+```bash
+mempal search "auth decision clerk"
+mempal search "database decision" --wing myapp --json
+mempal search "token refresh bug" --wing myapp --room auth
+```
+
+### 5.5 生成上下文
+
+```bash
+mempal wake-up
+mempal context "how to handle auth" --include-evidence
+```
+
+---
+
+## 6. 核心 CLI 工作流
+
+### 6.1 Search 搜索
+
+搜索结果包含：
+- `drawer_id`、`content`、`wing`、`room`、`source_file`、`similarity`、`route`
+- 结构化 signals：`entities`、`topics`、`flags`、`emotions`、`importance_stars`
+
+```bash
+# JSON 结构化输出
+mempal search "auth decision" --json
+
+# 带邻居 chunk
+mempal search "bug fix" --with-neighbors
+
+# 过滤 memory kind
+mempal search "pattern" --memory-kind knowledge
+
+# 按 field/domain/tier 过滤
+mempal search "architecture" --field architecture --tier dao_ren --anchor-kind repo
+```
+
+**检索架构**：
+```
+query → BM25 (FTS5) → Vector (sqlite-vec) → RRF Fusion (k=60) → Wing/Room filter → Tunnel hints
+```
+
+### 6.2 Context 上下文组装
+
+`mempal context` 按 mind-model 层级组装运行指导：
+
+```
+dao_tian → dao_ren → shu → qi → evidence（可选）
+```
+
+```bash
+# 基础 context（dao_tian 默认最多 1 条）
+mempal context "how to handle auth"
+
+# 包含 evidence
+mempal context "migration pattern" --include-evidence
+
+# 包含 knowledge cards
+mempal context "architecture" --include-cards
+
+# 提高 dao_tian 预算
+mempal context "core principles" --dao-tian-limit 3
+
+# JSON 输出
+mempal context "auth pattern" --format json --max-items 20
+```
+
+### 6.3 Brief 认知要点
+
+`mempal brief` 生成确定性 citation-first 认知要点，不调用 LLM、不写 DB：
+
+```bash
+mempal brief "current project state"
+```
+
+输出：summary / key_facts / evidence / cards / entities / unresolved / uncertainty / next_actions
+
+### 6.4 跨项目管理
+
+```bash
+# 列出所有项目
+mempal projects
+mempal projects --format json
+
+# 模糊 resume 项目
+mempal resume mempal
+mempal resume "my app" --evidence-limit 3 --format json
+```
+
+### 6.5 删除与清理
+
+```bash
+# 软删除
+mempal delete drawer_xxx
+
+# 永久清理
+mempal purge
+mempal purge --before 2026-04-10T00:00:00Z
+```
+
+### 6.6 Taxonomy 管理
+
+```bash
+# 查看
+mempal taxonomy list
+
+# 编辑关键词（改善路由精度）
+mempal taxonomy edit myapp deploy --keywords "render,railway,postgres,migration"
+```
+
+---
+
+## 7. 知识生命周期（Knowledge Lifecycle）
+
+Stage-1 knowledge drawer 的生命周期流程：
+
+```
+evidence → distill (candidate) → gate (检查门槛) → promote (active) → demote/retire
+```
+
+### 7.1 查看策略
+
+```bash
+mempal knowledge policy --format json
+```
+
+### 7.2 蒸馏（Distill）
+
+从 evidence drawers 创建候选 knowledge：
+
+```bash
+mempal knowledge distill \
+  --statement "Prefer evidence before asserting project facts" \
+  --content "When answering project-specific questions, cite source-backed memory." \
+  --tier dao_ren \
+  --supporting-ref drawer_evidence_1 \
+  --supporting-ref drawer_evidence_2 \
+  --field architecture \
+  --importance 3 \
+  --dry-run
+```
+
+- 只能创建 `dao_ren` 或 `qi` 的 candidate
+- `dao_tian` 和 `shu` 不开放 candidate 状态
+
+### 7.3 Gate（门槛检查）
+
+```bash
+mempal knowledge gate drawer_knowledge --format json
+mempal knowledge gate drawer_dao_tian --target-status canonical --reviewer human --format json
+```
+
+### 7.4 Promote（提升）
+
+```bash
+mempal knowledge promote drawer_knowledge \
+  --status promoted \
+  --verification-ref drawer_evidence_1 \
+  --reason "validated across repeated runs" \
+  --reviewer "human"
+```
+
+### 7.5 Demote（降级）
+
+```bash
+mempal knowledge demote drawer_knowledge \
+  --status demoted \
+  --evidence-ref drawer_counterexample \
+  --reason "new evidence contradicts this" \
+  --reason-type contradicted
+```
+
+### 7.6 Anchor Publication（锚点发布）
+
+```bash
+mempal knowledge publish-anchor drawer_knowledge \
+  --to repo \
+  --reason "stable across this repository"
+```
+
+---
+
+## 8. Phase-2 Knowledge Card
+
+Knowledge Card 是 Phase-2 的治理层，通过 `knowledge_cards` 表 + `knowledge_evidence_links`（role-separated）+ `knowledge_events`（append-only）提供更细粒度的知识治理。
+
+### 8.1 创建 Card
+
+```bash
+mempal knowledge-card create \
+  --statement "Always check repo docs before writing infra code" \
+  --content "When writing infrastructure code for this project..." \
+  --tier dao_ren \
+  --status candidate \
+  --field infrastructure
+```
+
+### 8.2 链接 Evidence
+
+```bash
+mempal knowledge-card link card_xxx drawer_evidence_1 --role supports --note "confirms the rule"
+mempal knowledge-card link card_xxx drawer_counter --role contradicts
+mempal knowledge-card link card_xxx drawer_lesson --role teaches
+```
+
+### 8.3 Gate → Promote/Demote
+
+```bash
+# 查看门槛
+mempal knowledge-card gate card_xxx --target-status promoted --format json
+
+# 提升（gate-enforced）
+mempal knowledge-card promote card_xxx \
+  --status promoted \
+  --verification-ref drawer_evidence_1 \
+  --reason "proven across 10+ sessions"
+
+# 降级
+mempal knowledge-card demote card_xxx \
+  --status demoted \
+  --evidence-ref drawer_counterexample \
+  --reason "new evidence contradicts this" \
+  --reason-type contradicted
+```
+
+### 8.4 检索 Card
+
+```bash
+mempal knowledge-card retrieve "infrastructure rules" --top-k 5 --format json
+```
+
+检索通过 linked evidence 反向查找 active cards，不改默认 search 行为。
+
+### 8.5 回填（Backfill）
+
+将 Stage-1 knowledge drawers 迁移到 Phase-2 cards：
+
+```bash
+# 预览
+mempal knowledge-card backfill-plan --tier dao_ren --status promoted
+mempal knowledge-card backfill-plan --field architecture --format json
+
+# 执行
+mempal knowledge-card backfill-apply --tier dao_ren --status promoted --execute
+```
+
+---
+
+## 9. Phase-3 自进化（Self-Evolution）
+
+Phase-3 是 mempal 的自进化基础设施，关注 **runtime adoption evidence** —— 即记录哪些 features 在生产中被接受/拒绝/遗漏/回滚。
+
+### 9.1 Recording 语义
+
+```bash
+# 查看 guidance
+mempal phase3 adoption guidance
+```
+
+四种 signal 类型：
+- `used`：agent 使用了这个 feature
+- `accepted`：agent 接受了输出（区别于 used）
+- `rejected`：agent 拒绝了输出
+- `miss`：应该出现但没有出现
+- `rollback`：需要回滚
+
+### 9.2 准备记录
+
+```bash
+# 只读生成 record 命令
+mempal phase3 adoption prepare-record \
+  --track context \
+  --signal used \
+  --feature include_cards \
+  --query "architecture" \
+  --card-id card_xxx
+```
+
+### 9.3 Capture 记录
+
+```bash
+# 显式 capture
+mempal phase3 adoption capture \
+  --surface "mempal_context" \
+  --outcome "accepted" \
+  --track context \
+  --signal accepted \
+  --feature include_cards \
+  --query "auth pattern" \
+  --execute
+
+# 检查质量
+mempal phase3 adoption check-record \
+  --track context \
+  --signal accepted \
+  --feature include_cards
+
+# 质量门控写入
+mempal phase3 adoption record-checked \
+  --track context \
+  --signal accepted \
+  --feature include_cards
+```
+
+### 9.4 Wrap（包装注入）
+
+```bash
+# 包裹一次命令执行并自动 capture
+mempal phase3 adoption wrap \
+  --track context \
+  --signal used \
+  --feature include_cards \
+  --execute \
+  -- mempal context "architecture" --include-cards
+```
+
+### 9.5 审查与分析
+
+```bash
+# 列出
+mempal phase3 adoption list --track context --limit 20
+
+# 统计
+mempal phase3 adoption stats --feature include_cards
+
+# 审查
+mempal phase3 adoption review --track context
+
+# 分析
+mempal phase3 adoption analytics
+```
+
+### 9.6 Card Context 默认开关
+
+```bash
+# 检查 readiness
+mempal phase3 readiness card-context
+
+# 生成提案
+mempal phase3 default-proposal card-context \
+  --rollback-criterion "adoption evidence below threshold"
+
+# 启用/禁用
+mempal phase3 default-control card-context --enable
+mempal phase3 default-control card-context --disable
+
+# 回滚
+mempal phase3 rollback-control card-context --execute
+```
+
+### 9.7 Evaluator Advisory
+
+```bash
+mempal phase3 evaluator advise \
+  --evaluator-id "evaluator_1" \
+  --subject-kind knowledge_card \
+  --subject-id card_xxx \
+  --proposed-action promote \
+  --evidence-ref drawer_evidence_1 \
+  --risk-note "insufficient counterexamples" \
+  --note "review before promotion"
+```
+
+### 9.8 Research Adapter
+
+```bash
+# 验证外部 research report
+mempal phase3 research-validate-plan /path/to/report.json
+
+# 预览或执行 research evidence ingest
+mempal phase3 research-ingest-plan /path/to/report.json
+mempal phase3 research-ingest-plan /path/to/report.json --execute
+```
+
+---
+
+## 10. MCP Server 与工具
+
+### 10.1 启动
+
+```bash
+mempal serve --mcp
+```
+
+### 10.2 MCP 工具完整列表（26 个）
+
+| # | 工具名 | 类型 | 用途 |
+|---|--------|------|------|
+| 1 | `mempal_status` | 只读 | schema 版本、drawer 计数、triple 统计、各 wing/room 分布、MEMORY_PROTOCOL |
+| 2 | `mempal_doctor` | 只读 | binary/PATH/schema 兼容性诊断 + MCP tool/action 能力清单 |
+| 3 | `mempal_search` | 只读 | BM25+向量+RRF 混合检索，返回结构化 signals（entities/topics/flags/emotions/importance_stars）+ tunnel hints |
+| 4 | `mempal_context` | 只读 | mind-model context：`dao_tian → dao_ren → shu → qi`，默认 `dao_tian_limit=1`，支持 `include_evidence`/`include_cards` |
+| 5 | `mempal_brief` | 只读 | deterministic citation-first 认知要点（不调用 LLM、不写 DB） |
+| 6 | `mempal_field_taxonomy` | 只读 | recommended field 值列表（guidance only） |
+| 7 | `mempal_knowledge_distill` | 写 | 从 evidence refs 创建 candidate knowledge drawer |
+| 8 | `mempal_knowledge_policy` | 只读 | Stage-1 promotion 阈值表 |
+| 9 | `mempal_knowledge_gate` | 只读 | 评估 knowledge drawer 是否满足 promotion 门槛 |
+| 10 | `mempal_knowledge_promote` | 写 | gate-enforced knowledge promotion |
+| 11 | `mempal_knowledge_demote` | 写 | evidence-backed knowledge demotion |
+| 12 | `mempal_knowledge_publish_anchor` | 写 | metadata-only outward anchor publication |
+| 13 | `mempal_knowledge_cards` | 读写 | Phase-2 card list/get/events/gate/promote/demote/retrieve |
+| 14 | `mempal_phase3` | 读写 | Phase-3 adoption: guidance/prepare_record/capture/check_record/record_checked/review/readiness/analytics/record/list/stats/gate/research_validate_plan/research_ingest_plan/evaluator_advise/default_proposal/instrumentation_policy |
+| 15 | `mempal_ingest` | 写 | 存储记忆（支持 `dry_run`，暴露 `lock_wait_ms`） |
+| 16 | `mempal_delete` | 写 | 软删除 + audit |
+| 17 | `mempal_taxonomy` | 读写 | 路由关键词管理 |
+| 18 | `mempal_kg` | 读写 | 知识图谱：add/query/invalidate/timeline/stats |
+| 19 | `mempal_tunnels` | 读写 | 跨 wing 链接发现与管理 |
+| 20 | `mempal_projects` | 只读 | 列出所有项目（wing + worktree + 计数 + 最近活动） |
+| 21 | `mempal_resume` | 只读 | 模糊匹配项目名并返回路径 + 最近决策 + 下一步 |
+| 22 | `mempal_peek_partner` | 只读 | 读 partner agent live session（可选 `cwd` 跨项目） |
+| 23 | `mempal_session_peek` | 只读 | 按 `tool + cwd` 显式读 session（同工具/跨项目） |
+| 24 | `mempal_cowork_push` | 写 | 投递 ephemeral handoff → partner inbox |
+| 25 | `mempal_cowork_bus` | 读写 | 多 agent bus: register/list/send/broadcast/drain/events/deliveries/ack/heartbeat/channel_set/channel_list/channel_send/tmux_peek/doctor/session_create/session_list/session_status/session_close/handoff/capture |
+| 26 | `mempal_fact_check` | 只读 | 离线矛盾检测（SimilarNameConflict/RelationContradiction/StaleFact） |
+
+### 10.3 常用 MCP 请求示例
+
+**搜索**：
+```json
+{
+  "query": "auth decision clerk",
+  "wing": "myapp",
+  "top_k": 5
+}
+```
+
+**存储**：
+```json
+{
+  "content": "decided to use Clerk for auth",
+  "wing": "myapp",
+  "room": "auth",
+  "source": "/repo/README.md"
+}
+```
+
+**预览（dry_run）**：
+```json
+{
+  "content": "decided to use Clerk for auth",
+  "wing": "myapp",
+  "dry_run": true
+}
+```
+
+**删除**：
+```json
+{
+  "drawer_id": "drawer_myapp_auth_1234abcd"
+}
+```
+
+**Cowork Push**：
+```json
+{
+  "target_tool": "codex",
+  "cwd": "/path/to/project",
+  "message": "I've finished the auth refactor. Next: remove old Auth0 code."
+}
+```
+
+### 10.4 MEMORY_PROTOCOL
+
+MCP 服务器在 `initialize.instructions` 字段中嵌入全部 MEMORY_PROTOCOL，任何 MCP 客户端连接时自动学习工作流——零配置。协议包含 18 条规则（Rule 0-17），覆盖搜索纪律、context vs wake-up 边界、ingest 入口点、知识生命周期、cowork 通信等。
+
+---
+
+## 11. 多 Agent 协作（Cowork）
+
+### 11.1 核心原语
+
+mempal 提供三个层次的 cowork：
+
+1. **Legacy Cowork（P6/P8）**：`mempal_peek_partner` + `mempal_cowork_push`，Claude ↔ Codex 双 agent
+2. **Multi-Agent Bus（P84-P90）**：`mempal_cowork_bus`，多 agent concrete `agent_id` 总线
+3. **Team Sessions（P94-P96）**：session create/list/status/close + handoff + capture
+
+### 11.2 安装 Hooks
+
+```bash
+mempal cowork-install-hooks --global-codex
+```
+
+这写入：
+- `.claude/hooks/user-prompt-submit.sh` + `.claude/settings.json` 对应条目
+- `~/.codex/hooks.json`（需要 `codex features enable codex_hooks`）
+
+> **注意**：Codex 侧需要重启 TUI 才能识别新 hooks 配置。
+
+### 11.3 Legacy Cowork 流
+
+```bash
+# Claude 查看 Codex 在干什么
+mempal cowork-peek --tool codex --cwd "$PWD"
+
+# Claude 向 Codex 推送消息
+mempal cowork-send --from claude --to codex --cwd "$PWD" --message "done with auth"
+
+# Codex 排空 inbox（hook 自动调用）
+mempal cowork-drain --target codex --cwd-source stdin-json --format codex-hook-json
+```
+
+### 11.4 Multi-Agent Bus 流
+
+```bash
+# 注册 agent
+mempal cowork-register --agent-id claude-main --tool claude --cwd "$PWD" --transport tmux --tmux-target "session:0.0"
+mempal cowork-register --agent-id codex-rev --tool codex --cwd "$PWD" --transport inbox
+
+# 发送
+mempal cowork-send --from claude-main --to codex-rev --cwd "$PWD" --message "review PR #42"
+
+# 广播
+mempal cowork-broadcast --from claude-main --to codex-rev --to claude-test --cwd "$PWD" --message "urgent: rollback"
+
+# Channel 通信
+mempal cowork-channel-set --cwd "$PWD" --channel review --agent-id claude-main --agent-id codex-rev
+mempal cowork-channel-send --from claude-main --cwd "$PWD" --channel review --message "ready for review"
+
+# 诊断
+mempal cowork-doctor --cwd "$PWD" --probe-tmux
+
+# 心跳
+mempal cowork-heartbeat --agent-id claude-main --cwd "$PWD"
+```
+
+### 11.5 Team Session 流
+
+```bash
+# 创建 session
+mempal cowork-session-create --cwd "$PWD" \
+  --session-id sprint-42 \
+  --title "Sprint 42 Auth Migration" \
+  --goal "Migrate auth from Auth0 to Clerk" \
+  --agent claude-main \
+  --agent codex-rev \
+  --channel review
+
+# 查看 session
+mempal cowork-sessions --cwd "$PWD"
+
+# 生成 handoff
+mempal cowork-handoff --cwd "$PWD" --session-id sprint-42
+
+# 关闭 session + capture handoff
+mempal cowork-session-close --cwd "$PWD" --session-id sprint-42 --capture --execute
+```
+
+### 11.6 已知限制
+
+1. **Codex `codex_hooks` feature flag**：需要手动启用 `codex features enable codex_hooks`
+2. **TUI 重启**：Codex/Claude Configuration 缓存，修改后需重启
+3. **MCP server re-spawn**：升级 mempal binary 后重启 Claude Code
+4. **At-next-submit**：push 在 partner 下一次用户 prompt 时才可见，非实时
+5. **Scope**：mempal_cowork_push 仅 Claude ↔ Codex 家族
+
+---
+
+## 12. Agent Diary
+
+Agent Diary 是一种跨 session 行为学习约定，使用已有工具：
+
+```bash
+# 写入 diary（通过 MCP mempal_ingest，convention: wing="agent-diary", room=agent-name）
+# 内容前缀：OBSERVATION: / LESSON: / PATTERN:
+
+# 搜索 diary
+mempal search "lesson" --wing agent-diary
+mempal search "pattern infrastructure" --wing agent-diary --room claude
+```
+
+| 前缀 | 用途 |
+|------|------|
+| `OBSERVATION:` | 事实行为观察 |
+| `LESSON:` | 从错误/成功中提炼的经验 |
+| `PATTERN:` | 跨 session 的重复行为模式 |
+
+---
+
+## 13. 知识图谱（Knowledge Graph）
+
+三元组支持时态有效性（`valid_from`/`valid_to`），可手动失效：
+
+```bash
+# 添加
+mempal kg add "Kai" "recommends" "Clerk"
+mempal kg add "Clerk" "replaced" "Auth0" --source-drawer drawer_xxx
+
+# 查询
+mempal kg query --subject Kai
+mempal kg query --predicate recommends
+mempal kg query --all
+
+# 时间线
+mempal kg timeline "Kai"
+
+# 统计
+mempal kg stats
+mempal kg list
+```
+
+---
+
+## 14. AAAK 输出格式化
+
+AAAK 是纯输出侧格式，不影响存储和检索：
+
+```bash
+mempal compress "Kai recommended Clerk over Auth0 based on pricing and DX"
+# V1|manual|compress|1744156800|cli
+# 0:KAI+CLK+AUT|kai_clerk_auth0|"Kai recommended Clerk..."|★★★★|determ|DECISION
+```
+
+中文支持（jieba-rs POS tagging）：
+```bash
+mempal compress "张三推荐Clerk替换Auth0，因为价格更优"
+```
+
+---
+
+## 15. 事实核查（Fact Check）
+
+离线、零 LLM、零网络，检测三种问题：
+
+| 问题类型 | 触发条件 |
+|---------|---------|
+| `SimilarNameConflict` | 文本中提到与已知 entity Levenshtein 距离 ≤2 的名字 |
+| `RelationContradiction` | 文本断言与已有 KG triple 冲突 |
+| `StaleFact` | 文本中的 triple 在 KG 中 `valid_to < now` |
+
+```bash
+# 检查文件
+mempal fact-check path/to/notes.txt --wing myapp
+
+# 检查 stdin
+echo "Kai stopped using Clerk" | mempal fact-check --wing myapp
+```
+
+---
+
+## 16. Auto-Dream 集成
+
+在项目 `CLAUDE.md` 中添加：
+
+```markdown
+## Auto-Dream Integration
+
+When performing auto-dream or manual dream:
+1. Call mempal_search to verify facts being consolidated
+2. Save high-value insights to mempal (mempal_ingest, importance >= 3)
+3. If MEMORY.md and mempal contradict, trust mempal (has citations)
+4. Write dream summary as agent diary (wing="agent-diary", room="claude")
+5. Check triples for expired relationships to invalidate
+```
+
+---
+
+## 17. 开发命令
+
+```bash
+# 测试
+cargo test --workspace
+cargo test --workspace --all-features
+
+# Lint
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+cargo fmt --all --check
+
+# 重新嵌入
+mempal reindex
+mempal reindex --stale
+mempal reindex --force --dry-run
+
+# 基准测试
+mempal bench longmemeval /path/to/longmemeval_s_cleaned.json --limit 20
+mempal bench longmemeval /path/to/data.json --mode aaak --granularity turn --out results.jsonl
+```
+
+---
+
+## 18. MEMORY_PROTOCOL
+
+协议嵌入在 `mempal_status` 和 `mempal wake-up` 的输出中，共 18 条规则（Rule 0-17）：
+
+- **Rule 0**：每 session 先调 `mempal_status` 发现 wings
+- **Rule 1**：wake-up 是 L0/L1 刷新，不是 typed context
+- **Rule 2**：搜索优先用 `wing="mempal"` 缩小范围
+- **Rule 3**：历史决策问题默认 `top_k=2`，不足再放大
+- **Rule 3a**：非英语 query 翻译为英语
+- **Rule 4**：每次 commit 后用 `mempal_ingest` 保存决策
+- **Rule 5**：显式消费结构化 signals（flags/entities/importance_stars）
+- **Rule 5a**：session 结束写 diary 条目
+- **Rule 6**：大响应重试更窄范围
+- **Rule 7**：`content` 是 raw text，不期待 AAAK 格式
+- **Rule 8**：基于 mempal 结果作答时引用 `drawer_id` 和 `source_file`
+- **Rule 9**：没找到高信号结果明确说明，不猜测
+- **Rule 10**：`mempal_context` 用于 workflow/skill/tool 选择（不自动执行）
+- **Rule 11**：assert entity 关系前运行 `mempal_fact_check`
+- **Rule 12**：`mempal_ingest` 默认写 evidence，knowledge-only 字段被拒
+- **Rule 13**：cowork push 用于 transient status update
+- **Rule 14**：`mempal_peek_partner` 不要 self-peek
+- **Rule 15**：`mempal_knowledge_distill` 创建 candidate，不自动 promote
+- **Rule 16**：`mempal_brief` 用于快速认知定位
+- **Rule 17**：`mempal_phase3` 用于 recording runtime adoption
+
+---
+
+## 19. FAQ
+
+### 搜索结果不对
+
+- 加 `--wing` 明确范围
+- 加 `--room` 锁定子系统
+- 检查 taxonomy：`mempal taxonomy list`
+- 非英语查询翻译为英语
+
+### 中文搜索效果差
+
+翻译为英语查询，或使用 `--wing`/`--room` 缩小范围。
+
+### 为什么 source_file 是相对路径
+
+保持引用稳定，无论通过绝对或相对路径导入。
+
+### 切换嵌入模型后
+
+运行 `mempal reindex` 重新嵌入所有 drawers。
+
+### delete 是软删除吗
+
+是。`mempal delete` 标记软删除，`mempal purge` 永久移除。
+
+---
+
+## 参考文档
+
+- 设计文档：`docs/specs/2026-04-08-mempal-design.md`
+- 使用指南：`docs/usage.md`
+- AAAK 方言：`docs/aaak-dialect.md`
+- Cowork Runbook：`docs/COWORK-RUNBOOK.md`
+- Maintenance Runbook：`docs/MAINTENANCE-RUNBOOK.md`
+- 基准测试：`benchmarks/longmemeval_s_summary.md`
+- 在线书籍：[MemPalace: AI 记忆的第一性原理](https://zhanghandong.github.io/mempalace-book/)