whimsicality-db

面向长期运行代理的工作日志。基于 SQLite 的 MCP 服务器，支持会话跟踪、事件记录和 FTS5 搜索——让跨多个上下文窗口工作的代理能够回忆决策、搜索过往事件并跟踪自身进度。

为什么存在

执行长期任务的代理面临一个问题：当上下文窗口填满时，它们会丢失对已做决策、已尝试方案和待办事项的跟踪。对话历史滚动消失后，代理会重新推导出它已经得出的结论。

whimsicality-db 通过持久化工作日志解决这一问题：

1. 为任务创建会话：db_session_create({ id: "refactor-auth", name: "Refactor auth system" })

2. 实时记录事件：db_event_log({ session_id: "refactor-auth", event_type: "decision", content: "Chose JWT over session cookies for stateless auth" })

3. 搜索过往决策：db_search({ query: "auth decision", collections: ["events"] })

4. 跨上下文窗口跟踪待办事项：db_todo_add({ title: "Implement JWT verification", session_id: "refactor-auth" })

当代理在上下文窗口重置后回来时，它会搜索会话日志并从上次中断的地方继续——无需重新阅读整个对话。

Related MCP server: MCP Tools

快速开始

{
  "mcpServers": {
    "whimsicality-db": {
      "command": "npx",
      "args": ["whimsicality-db"]
    }
  }
}

数据存储在 ~/.whimsicality/db-storage/whimsicality.db（SQLite，WAL 模式）。设置 WHIMSICALITY_DB_DIR 可覆盖默认路径。

从 whimsicality-mcp 迁移

如果你使用了已弃用的 whimsicality-mcp 包，请导入你的数据：

db_import({ source_dir: "~/.whimsicality/mcp-storage" })

将记忆条目、文档和压缩缓存块导入统一的条目表。

工具（共 21 个，schema 约 2,700 tokens）

记忆 — 键值事实（4）

条目 — 带自动压缩的统一文本存储（5）

取代旧的 docs、cache 和 context 集合。小文本按原样存储并进行 FTS5 索引。大文本（>64KB）使用 brotli 自动压缩，读取时分页。标签和来源为可选项。

待办事项 — 跨上下文窗口的任务跟踪（4）

会话 — 长期任务容器（3）

事件 — 会话日志（2）

搜索 + 统计 + 导入（3）

架构

┌──────────────────────────────────────────────────────────┐
│ SQLite Database (WAL mode)                               │
│                                                          │
│  memory       ─── memory_fts (FTS5)                     │
│  entries      ─── entries_fts (FTS5)                    │
│    ├─ small:  content_text (plain, FTS5-indexed)        │
│    └─ large:  content (brotli BLOB) + title (FTS5)      │
│  entry_tags   ── normalized tag join table               │
│  todos        ─── todos_fts  (FTS5)                     │
│  todo_tags    ── normalized tag join table               │
│  sessions     (no FTS — small, direct query)            │
│  events       ─── events_fts (FTS5)                     │
│                                                          │
│  Triggers keep FTS5 indexes in sync automatically.      │
│  WAL mode: concurrent readers + 1 writer.               │
│  CHECK constraints on status columns.                   │
│  Schema version migrations (v1→v2→v3).                  │
└──────────────────────────────────────────────────────────┘

统一搜索

db_search({ query, collections, top_k }) 在一次调用中跨记忆、条目、待办事项和事件进行搜索。结果合并后按 BM25 分数排序（分数越高越好）。每个结果包含其集合、ID、分数，以及适用时的匹配中心摘要。

自动压缩

超过 64KB 的条目会自动进行 brotli 压缩。标题/摘要以纯文本存储用于 FTS5 索引。db_entry_read 按需解压，支持 offset+length 分页。

原生模块说明

此包依赖 better-sqlite3，这是一个原生 Node.js 插件。npm install 通常会自动找到预编译二进制文件。如果没有，node-gyp 会从源码编译——你需要 Python 3 和 C++ 编译器。Node 22.5+ 内置了带 FTS5 的 node:sqlite，这是未来零依赖的路径。

Schema 迁移

schema_version 表跟踪数据库 schema 版本。打开时，服务器读取版本并按顺序应用迁移：v1→v2（标签连接表）、v2→v3（合并 docs/cache/context 的统一条目表）。

何时使用哪个集合

• 记忆：希望通过精确键回忆的小型键值对（事实、配置）

• 条目：任何文本内容——文档、参考资料、大段内容。自动压缩、标签可选、分页读取

• 待办事项：模型跨上下文窗口跟踪的任务

• 会话：长期任务容器（分组事件和待办事项）

• 事件：会话内按时间顺序的日志（决策、里程碑、错误）

配置

开发

git clone https://github.com/WhimsicalityLabs/Whimsicality-DB.git
cd Whimsicality-DB
npm install
npm test

67 个测试：64 个进程内测试（存储、搜索、条目、待办事项、会话、事件、验证、导入）+ 3 个 bin 冒烟测试（启动实际的 bin/whimsicality-db.js 入口点）。

许可证

MIT