Mempal — Development skill for Claude Code

mempal

本文件是仓库级 agent 工作约束，内容与 `CLAUDE.md` 保持一致；在本仓库内工作的 agent 都应遵循以下规则。

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

Skills

**必须使用项目内的 Rust 技能**：`skills/rust-skills/SKILL.md`

编写、审查、调试、重构 Rust 代码时，遵循该 skill 的四步工作流（理解 → 服从 → 释放 → 约束）和概念锚点框架。

参考实现

mempal 借鉴 MemPalace 的设计理念（verbatim 存储、Wing/Room 结构、AAAK 压缩），用 Rust 从零实现并修复其缺陷。以下两个本地项目是关键参考：

• MemPalace 源码：/Users/zhangalex/Work/Projects/AI/mempalace — Python 原版实现，查看 mempalace/ 目录下的 searcher.py、palace_graph.py、dialect.py、knowledge_graph.py 等模块了解原始设计
• MemPalace 书稿：/Users/zhangalex/Work/Projects/AI/mempalace-book — 基于源码的设计分析书，book/src/ 下 25 章 + 4 个附录，包含架构评估、AAAK 完整度分析、benchmark 诚实性审查等深度内容

实现时遇到设计疑问，优先查阅书稿中的分析（特别是附录 C 的 AAAK 评估和附录 A/B 的 E2E Trace），而非直接复制 Python 代码。

设计文档

`docs/specs/2026-04-08-mempal-design.md` — 完整架构设计，所有实现必须以此为准。

Spec 体系

项目使用 agent-spec 管理任务合约。所有实现必须对照 spec 验收。

项目级 Spec

• specs/project.spec.md — 项目约束（edition、依赖、编码规范、架构不变量）

任务 Spec（按优先级）

Spec	范围	依赖	估时
specs/p0-core-scaffold.spec.md	workspace 骨架 + SQLite schema	无	1d
specs/p0-embed-trait.spec.md	Embedder trait + ONNX 实现	core	1d
specs/p0-ingest.spec.md	导入管道（格式检测/归一化/分块/存储）	core + embed	2d
specs/p0-search-cli.spec.md	搜索引擎 + CLI（init/ingest/search）	core + embed + ingest	2d
specs/p1-routing-citation.spec.md	查询路由 + 引用组装 + wake-up	search-cli	1d
specs/p2-mcp.spec.md	MCP 服务器（4 工具）	routing	1d
specs/p3-aaak.spec.md	AAAK 编解码（BNF + 往返验证）	core（独立）	2d
specs/p4-rest-api.spec.md	REST API（feature-gated）	routing	1d

关键路径

core(1d) → embed(1d) → ingest(2d) → search-cli(2d) → routing(1d) → mcp(1d)
                                                                    → rest(1d)
core(1d) → aaak(2d)  ← 可并行

Spec 使用方式

# 查看任务合约
agent-spec parse specs/p0-core-scaffold.spec.md

# 验证质量
agent-spec lint specs/p0-core-scaffold.spec.md --min-score 0.7

# 开始实现前：读 spec → 理解 intent/decisions/boundaries → 按 scenarios 验收

实现计划

`docs/plans/2026-04-08-p0-implementation.md` — P0 关键路径的完整实现计划（10 个 Task，TDD 流程）。

每个 Task 包含：写失败测试 → 验证失败 → 实现 → 验证通过 → 提交。按顺序执行：

1. Workspace scaffold + stub crates
2. Core data types
3. SQLite Database + schema
4. Config loading
5. Embedder trait + ONNX
6. Ingest — format detection + chunking
7. Ingest — full pipeline with storage
8. Search engine
9. CLI — init, ingest, search, status
10. Integration + cleanup

开始实现时：**先读对应的 spec（`specs/p0-*.spec.md`），再按 plan 的 Task 步骤执行。**

关键架构约束

• 存储：SQLite + sqlite-vec，单文件 ~/.mempal/palace.db
• 嵌入：ONNX 默认（MiniLM），可选外部 API，通过 Embedder trait 抽象
• AAAK 是输出格式化器：不被 ingest 或 search 依赖，只在 CLI/MCP 输出侧可选调用
• 数据永远 raw 存储：drawers 表存原文，向量索引在 drawer_vectors 表
• 搜索结果强制带引用：每个 SearchResult 必须包含 source_file 和 drawer_id

Workspace 结构

crates/
├── mempal-core/      # 数据模型 + SQLite schema + taxonomy
├── mempal-ingest/    # 导入管道
├── mempal-search/