spool-memory 0.2.3

# Spool

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

## 问题

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

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

## 特性

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

## 快速开始

```bash
# 方式 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 知识库 (笔记)   │      │
│  └──────────────┘  └─────────────────────────┘      │
└─────────────────────────────────────────────────────┘
```

**运行面：**

| 二进制文件 | 用途 |
|-----------|------|
| `spool` | CLI：检索、唤醒、生命周期、钩子 |
| `spool-mcp` | MCP stdio 服务器（20+ 工具） |
| `spool-daemon` | 可选的只读生命周期守护进程 |
| `spool-gui` | 桌面工作台（需启用 `gui` feature） |

## 工作原理

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

## 配置

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

关键配置段：

```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`，命令会快速失败

## 使用方法

### 上下文检索

```bash
# 获取任务上下文（供 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
```

### 记忆生命周期

```bash
# 列出待审核的记忆
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 服务器

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

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

## 对比

| 特性 | Spool | mem0 | Khoj | LLM Wiki |
|------|-------|------|------|----------|
| 本地优先 | 是 | 云端 | 自托管 | 本地 |
| 结构化记忆 | 带生命周期的类型化记录 | 键值对 | 文档 | Wiki 页面 |
| 多工具支持 | MCP + CLI | API | API | 手动 |
| Obsidian 集成 | 原生 | 无 | 无 | 无 |
| 隐私 | 完全本地 | 云存储 | 取决于部署 | 本地 |
| 记忆生命周期 | 草稿→权威 | 扁平 | 扁平 | 手动 |
| 自动提炼 | 是 | 否 | 否 | 否 |
| BM25 检索 | 可选 | 向量 | 向量 | 无 |
| 知识整合 | 自动聚合+修剪 | 无 | 无 | LLM lint |

## 从源码构建

```bash
# 前置条件：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](CONTRIBUTING.md) 了解开发环境搭建、代码风格和 PR 流程。

## 许可证

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

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT License ([LICENSE-MIT](LICENSE-MIT))

由你选择。