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. コンテキストウィンドウをまたいでTODOを追跡: 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、スキーマ~2,700トークン）

メモリ — キーと値のファクト（4）

エントリ — 自動圧縮付き統合テキストストア（5）

古いdocs、cache、contextコレクションを置き換えます。小さなテキストはそのまま保存され、FTS5でインデックス化されます。大きなテキスト（>64KB）はbrotliで自動圧縮され、読み取り時にページングされます。タグとソースはオプションです。

TODO — コンテキストウィンドウをまたいだタスク追跡（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 }) は、メモリ、エントリ、TODO、イベントを1回の呼び出しで検索します。結果はマージされ、BM25スコア（高いほど良い）でランク付けされます。各結果には、コレクション、ID、スコア、および該当する場合はマッチ中心の抜粋が含まれます。

自動圧縮

64KBを超えるエントリは自動的にbrotli圧縮されます。タイトル/サマリーはFTS5インデックス用にプレーンテキストとして保存されます。db_entry_read はoffset+lengthページングでオンデマンドに解凍します。

ネイティブモジュールに関する注意

このパッケージはネイティブNode.jsアドオンである better-sqlite3 に依存しています。npm install は通常、プリビルドバイナリを自動的に見つけます。見つからない場合は、node-gyp がソースからコンパイルします — Python 3とC++コンパイラが必要です。Node 22.5+にはFTS5が組み込まれた node:sqlite が同梱されており、将来のゼロ依存パスです。

スキーママイグレーション

schema_version テーブルはデータベーススキーマのバージョンを追跡します。オープン時に、サーバーはバージョンを読み取り、マイグレーションを順次適用します：v1→v2（タグ結合テーブル）、v2→v3（docs/cache/contextを統合したエントリテーブル）。

どのコレクションをいつ使うか

• メモリ: 正確なキーで呼び出したい小さなキーと値のペア（ファクト、設定）

• エントリ: 任意のテキストコンテンツ — ドキュメント、参照、大きなコンテンツ。自動圧縮、タグはオプション、ページング読み取り

• TODO: モデルがコンテキストウィンドウをまたいで追跡しているタスク

• セッション: 長期タスクのコンテナ（イベントとTODOをグループ化）

• イベント: セッション内の時系列ログ（決定、マイルストーン、エラー）

設定

開発

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

67テスト：64のインプロセステスト（ストア、検索、エントリ、TODO、セッション、イベント、バリデーション、インポート）+ 3のbinスモークテスト（実際の bin/whimsicality-db.js エントリポイントを起動）。

ライセンス

MIT