mempal

Coding agent 的项目记忆工具。单二进制，cargo install mempal，10 秒内带出处找回历史决策。

做什么

Agent 写代码 → 提交 → mempal 保存决策上下文
下一个 session（任何 agent）→ mempal search → 带出处找回决策

• 混合检索：BM25 关键词匹配 + 向量语义搜索，通过 RRF（Reciprocal Rank Fusion）融合
• 知识图谱：subject-predicate-object 三元组，支持时态验证（valid_from/valid_to）
• 跨项目隧道：自动发现多个 Wing 中同名 Room 的链接
• 自描述协议：MEMORY_PROTOCOL 嵌入 MCP ServerInfo，任何 agent 连接后自动学会使用方式——无需系统提示配置
• 多语言：model2vec-rs（BGE-M3 蒸馏）作为默认嵌入器，零原生依赖
• 单文件：所有数据在 ~/.mempal/palace.db（SQLite + sqlite-vec）

快速开始

cargo install --path crates/mempal-cli --locked

mempal init ~/code/myapp
mempal ingest ~/code/myapp --wing myapp
mempal search "auth decision clerk"
mempal wake-up

启用 REST 支持：

cargo install --path crates/mempal-cli --locked --features rest

配置

配置文件 ~/.mempal/config.toml（可选，不存在时使用默认值）：

db_path = "~/.mempal/palace.db"

[embed]
backend = "model2vec"                          # 默认，零原生依赖
# model = "minishlab/potion-multilingual-128M" # 默认多语言模型

其他后端：

# 本地 ONNX（需要 --features onnx）
[embed]
backend = "onnx"

# 外部 API
[embed]
backend = "api"
api_endpoint = "http://localhost:11434/api/embeddings"
api_model = "nomic-embed-text"

命令一览

| 添加知识图谱三元组 | |mempal kg query [--subject S] [--predicate P]| 查询三元组 | |mempal kg timeline | 实体的时间线视图 | |mempal kg stats| 知识图谱统计 | |mempal tunnels| 跨 Wing room 链接 | |mempal taxonomy list / edit| 管理路由关键词 | |mempal reindex| 切换模型后重新嵌入所有 drawer | |mempal status| 数据库统计、schema 版本、scope 分布 | |mempal serve [--mcp]| MCP 服务器（+ REST） | |mempal cowork-install-hooks [--global-codex]| 一键安装 Claude Code + Codex 的 UserPromptSubmit hook | |mempal cowork-drain --target | 排空 inbox（供 hook 调用，任意错误均 exit 0） | |mempal cowork-status --cwd

MCP 服务器（10 个工具）

mempal serve --mcp 通过 Model Context Protocol 暴露：

服务器在 MCP initialize.instructions 中嵌入 MEMORY_PROTOCOL（11 条行为规则），任何 MCP 客户端自动接收。

记忆协议

mempal 通过自描述教 agent 这些规则：

1. 首次设置 — 调用 mempal_status 发现 wing 名称
2. 唤醒 — 不同客户端有不同的预加载机制
3. 断言前验证 — 陈述项目事实前先搜索
4. 不确定时查询 — "我们为什么..."、"上次我们..." 3a. 翻译为英文 — 非英文查询先翻译再搜索
5. 决策后保存 — 保存理由，不仅是结果
6. 引用一切 — 引用 drawer_id 和 source_file 5a. 记日记 — session 结束时在 wing="agent-diary" 下记行为观察
7. Partner 感知 — 问 partner 当前状态用 mempal_peek_partner（live session），问已沉淀决策才用 mempal_search
8. 决策沉淀 — mempal_ingest 只存已达成的硬决策；partner 参与时要把 partner 的关键贡献带进 drawer 正文
9. COWORK PUSH — mempal_cowork_push 是 SEND 原语，at-next-submit 交付、非实时；别用它做该 ingest 的事
10. 入库前校验 — 在 ingest 含 entity 关系断言的决策前调 mempal_fact_check，它抓相似名拼错、KG 关系矛盾、以及 valid_to 已过期的 stale fact

并发 Ingest 安全（P9-B）

两个 agent 同时向同一个 source 写入以前是 TOCTOU race：两边都通过 dedup 检查、都 insert，结果重复 drawer 或 vector 错配。从 0.4.0 起 mempal_ingest 和 ingest_file_with_options 在进入 dedup + insert 临界区前获取 per-source 建议锁。

• 锁文件 ~/.mempal/locks/<16-hex>.lock，懒建，guard drop 时 OS 自动释放
• 默认 5s 超时，50ms 重试 + jitter；超时返回 LockError::Timeout
• 非 dry-run 的 ingest response 携带 lock_wait_ms: Option<u64>，agent 可据此察觉并发
• dry-run 不占锁（零写入，零 race）
• 0.4.0 仅覆盖 Unix（flock 内联 extern，不引 libc crate）；Windows 暂为 no-op 占位，后续用 LockFileEx 补齐

离线事实核查（P9-A）

mempal_fact_check（以及 CLI mempal fact-check）对一段文本在现有 KG triples + 最近 drawer 聚合的 entity registry 上做比对，标记三类确定性问题（不调 LLM、不走网络）：

文本 → 三元组当前支持三种窄模式："X is Y's ROLE"、"X works at / for Y"、"X is [the|a|an] ROLE of Y"。不认得的句型静默返回空，倾向少报不多报。协议 Rule 11 指导 agent 在 ingest 含实体关系断言的决策前跑一次。完整契约见 specs/p9-fact-checker.spec.md。

检索架构

query → BM25 (FTS5)         → 关键词排序
      → Vector (sqlite-vec) → 语义相似度排序
      → RRF 融合 (k=60)     → 合并排序
      → Wing/Room 过滤      → 范围限定
      → Tunnel 提示         → 跨项目引用

知识图谱

mempal kg add "Kai" "recommends" "Clerk"
mempal kg add "Clerk" "replaced" "Auth0" --source-drawer drawer_xxx
mempal kg timeline "Kai"
mempal kg stats

三元组支持时态验证——关系过期后可标记为无效。

Agent 日记

跨 session 行为学习——agent 记录观察、教训和模式：

# 搜索日记
mempal search "lesson" --wing agent-diary
mempal search "pattern" --wing agent-diary --room claude

日记通过现有的 mempal_ingest 工具写入，wing="agent-diary"，room=agent 名字。MEMORY_PROTOCOL Rule 5a 教 agent 在 session 结束时写日记。可与 Claude Code 的 auto-dream 集成，实现自动记忆整理。

导入格式（5 种）

AAAK 压缩

输出格式化器，任何 LLM 无需解码即可阅读：

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 over Auth0..."|★★★★|determ|DECISION

中文文本使用 jieba-rs 词性标注进行分词。

架构

关键设计： - model2vec-rs 默认嵌入——零原生依赖，多语言（BGE-M3 蒸馏） - ort (ONNX) 通过 onnx feature flag 可选启用 - FTS5 BM25 关键词搜索——通过 SQLite 触发器同步 - 软删除 + 审计日志——mempal delete + mempal purge - 重要性排序——drawer 有 0-5 重要性评分，wake-up 按重要性排序 - 语义去重——ingest 时检测相似内容，warning 但不阻塞

开发

cargo test --workspace
cargo test --workspace --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo fmt --all --check

切换嵌入模型后重建向量：

mempal reindex

文档

• 设计文档：docs/specs/2026-04-08-mempal-design.md
• 使用指南：docs/usage.md
• AAAK 方言：docs/aaak-dialect.md
• Spec 体系（仓库内部 agent-spec 合约，GitHub 查看）：https://github.com/ZhangHanDong/mempal/tree/main/specs
• 实现计划（仓库内部实现计划，GitHub 查看）：https://github.com/ZhangHanDong/mempal/tree/main/docs/plans
• Benchmark：benchmarks/longmemeval_s_summary.md