Spool

本地优先的开发者记忆系统 — 让你的 AI 编程工具拥有跨会话的持久化结构化记忆，无需云端依赖。

问题

每次开启新的 AI 编程会话，你都会丢失上下文。昨天做的决策、上周表达的偏好、上个月发现的模式 — 全部消失。你不得不反复向 Claude、Codex、Cursor 等工具重新解释相同的约束。

Spool 通过维护一个本地记忆层来解决这个问题，任何 AI 工具都可以从中读取。你的决策、偏好、工作流和项目知识在会话之间、工具之间持久保存。

特性

• 零基础设施 — 纯文件存储（JSONL 追加日志 + Obsidian 知识库）
• 多工具支持 — 通过 MCP 协议支持 Claude Code、Codex、Cursor、OpenCode
• 结构化记忆 — 不只是原始文本；带生命周期状态的类型化记录
• 自动提炼 — 从会话中提取决策、偏好、模式
• 生命周期管理 — 草稿 → 候选 → 已采纳 → 权威 → 已归档
• Obsidian 集成 — 与知识库笔记双向同步
• 隐私优先 — 一切留在本机，不外传数据
• 多运行面 — CLI、MCP 服务器、守护进程、桌面 GUI
• BM25 全文检索 — 可选的 tantivy 驱动混合检索（RRF 融合）
• 知识整合 — 碎片记忆自动聚合 + 过时知识自动归档

快速开始

# 方式 1：从 crates.io 安装（推荐）
cargo install spool-memory

# 方式 2：从源码安装
cargo install --path .

# 方式 3：Homebrew（macOS/Linux）
brew tap lukylong/spool
brew install spool-memory

# 初始化配置
spool init --vault /path/to/your/obsidian/vault

# 或手动创建配置
mkdir -p ~/.spool
cp spool.example.toml ~/.spool/config.toml
# 编辑配置文件设置你的 vault 路径

# 为你的 AI 工具安装 MCP 集成
spool mcp install --client claude --config ~/.spool/config.toml

# 验证安装
spool status --config ~/.spool/config.toml

配置完成后，你的 AI 会话启动时会自动接收相关记忆。

架构

┌─────────────────────────────────────────────────────┐
│                   AI 客户端                           │
│  (Claude Code, Codex, Cursor, OpenCode, ...)        │
└──────────────────────┬──────────────────────────────┘
                       │ MCP / CLI
┌──────────────────────▼──────────────────────────────┐
│                 Spool 核心 (Rust)                    │
├─────────────┬────────────┬──────────┬───────────────┤
│  检索引擎    │  生命周期   │  守护进程 │   桌面门面    │
│  Engine     │  Service   │  (只读)  │   Facade      │
├─────────────┴────────────┴──────────┴───────────────┤
│              存储层                                   │
│  ┌──────────────┐  ┌─────────────────────────┐      │
│  │ JSONL 日志   │  │ Obsidian 知识库 (笔记)   │      │
│  └──────────────┘  └─────────────────────────┘      │
└─────────────────────────────────────────────────────┘

运行面：

工作原理

1. 项目路由 — Spool 将当前工作目录匹配到配置的项目
2. 知识库扫描 — 扫描相关 Obsidian 知识库子树获取上下文
3. 评分 — 通过标题、标题层级、wikilinks、标签、frontmatter、实体、触发词对笔记排序
4. 记忆生命周期 — 将决策/偏好捕获为带溯源的结构化记录
5. 检索 — 在会话启动（wakeup）或按需时向 AI 工具提供正确的上下文

配置

配置文件位于 ~/.spool/config.toml。完整注释示例见 spool.example.toml。

关键配置段：

[vault]
root = "/path/to/your/obsidian/vault"

[output]
default_format = "prompt"
max_chars = 12000
max_notes = 8

[[projects]]
id = "my-project"
name = "My Project"
repo_paths = ["/path/to/repo"]
note_roots = ["10-Projects", "20-Areas"]

配置规则

• vault.root 必须是 Obsidian 知识库的绝对路径
• projects.repo_paths 与当前工作目录匹配
• note_roots 是相对于 vault 的路径；不允许 .. 转义
• 如果没有项目匹配当前 cwd，命令会快速失败

使用方法

上下文检索

# 获取任务上下文（供 AI 消费）
spool get --config ~/.spool/config.toml \
  --task "实现用户认证" \
  --cwd /path/to/repo \
  --target claude --format prompt

# 解释为什么选择了某些笔记
spool explain --config ~/.spool/config.toml \
  --task "实现用户认证" \
  --cwd /path/to/repo

记忆生命周期

# 列出待审核的记忆
spool memory list --config ~/.spool/config.toml --view pending-review

# 手动记录一条记忆
spool memory record-manual --config ~/.spool/config.toml \
  --title "偏好小函数" \
  --summary "保持函数在 50 行以内" \
  --memory-type preference --scope user \
  --source-ref manual:cli --actor dev

# 采纳一条提议的记忆
spool memory accept --config ~/.spool/config.toml \
  --record-id <id> --actor dev --reason "已验证"

# 知识整合：检测可合并的碎片记忆
spool memory consolidate --config ~/.spool/config.toml --dry-run

# 知识修剪：检测过时/被替代的记忆
spool memory prune --config ~/.spool/config.toml --dry-run

# 回填旧记录的结构化字段
spool memory sync-vault --config ~/.spool/config.toml --enrich --dry-run

MCP 服务器

# 启动 MCP 服务器供 AI 工具集成
spool-mcp --config ~/.spool/config.toml

# 带可选守护进程加速读取
spool-mcp --config ~/.spool/config.toml --daemon-bin spool-daemon

对比

从源码构建

# 前置条件：Rust 工具链（stable）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 克隆并构建
git clone https://github.com/lukylong/Spool.git
cd spool
cargo build --release

# 运行测试
cargo test

# 本地安装
cargo install --path .

# 启用 BM25 全文检索（可选）
cargo build --release --features bm25

贡献

参见 CONTRIBUTING.md 了解开发环境搭建、代码风格和 PR 流程。

许可证

本项目采用以下任一许可证：

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

由你选择。