whimsicality-db

A SQLite-backed MCP server with FTS5 full-text search for truly infinite agent context. Session tracking, event logging, todo management, and tagged context index for long-horizon tasks and heavy workloads.

Quick start

Add to your MCP client config:

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

Data is stored at ~/.whimsicality/db-storage/whimsicality.db by default (SQLite with WAL mode). Set WHIMSICALITY_DB_DIR to override.

Why SQLite?

The companion server whimsicality-mcp uses a JSON file for memory and docs. It's simple and correct, but every write rewrites the whole file and every search re-tokenizes the whole corpus. Fine for hundreds of entries, unusable for tens of thousands.

This server uses SQLite with FTS5:

What's different from whimsicality-mcp

Three new collections that the JSON server doesn't have:

Todos

Task tracking with status (pending/in_progress/completed), priority, tags, and session linkage. The model can add tasks, update their status, search them, and filter by tag or session. Useful for long-horizon work where the model needs to track its own progress across context window boundaries.

Context index

Tagged content entries that the model pulls by tag when needed. Instead of loading everything into context, the model stores reference material, architecture decisions, and domain knowledge with tags, then retrieves only what's relevant via db_context_by_tags(["security", "auth"]). This is the "multiple files with tags" pattern — the model has a dense catalog of tagged knowledge and pulls only what it needs.

Sessions + Events

Session tracking for long-horizon tasks. Create a session, log events (decisions, milestones, errors, observations) as they happen, and search them later. When a task spans multiple context windows, the session log is the persistent memory that connects them — the model can search past decisions and events without re-deriving them.

Tools (32 total)

Memory — namespaced key-value store (5)

Documents — full-text searchable (5)

Cache — compressed paged content (7)

Todos — task tracking (5)

Context index — tagged content retrieval (5)

Sessions — long-horizon task tracking (4)

Events — session log (3)

Stats (1)

Architecture

┌──────────────────────────────────────────────────────────┐
│ SQLite Database (WAL mode)                               │
│                                                          │
│  memory       ─── memory_fts (FTS5)                     │
│  docs         ─── docs_fts   (FTS5)                     │
│  cache        ─── cache_fts  (FTS5)                     │
│  todos        ─── todos_fts  (FTS5)                     │
│  context_entries ── context_fts (FTS5)                  │
│  sessions     (no FTS — small, direct query)            │
│  events       ─── events_fts (FTS5)                     │
│                                                          │
│  Triggers keep FTS5 indexes in sync automatically.      │
│  WAL mode allows concurrent readers + 1 writer.         │
└──────────────────────────────────────────────────────────┘

Every table with text content has a corresponding FTS5 virtual table with triggers that keep the index in sync on insert/update/delete. Searches use SQLite's native bm25() function for ranking — no re-tokenization, no recomputation.

The cache table stores content as brotli-compressed BLOBs. db_cache_read decompresses on demand with offset+length paging.

When to use which collection

• Memory: small key-value pairs you want to recall by exact key (facts, decisions, config)

• Docs: documents you want to search by content (returns matching excerpts)

• Cache: large content you want to page in on demand (compressed, paged reads)

• Todos: tasks the model is tracking across context windows (status, priority, tags)

• Context index: reference material the model pulls by tag when needed (architecture, domain knowledge, patterns)

• Sessions: long-horizon task containers (group events and todos)

• Events: chronological log within a session (decisions, milestones, errors)

Configuration

Development

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

The test suite covers all 32 tools: memory CRUD + search, docs CRUD + search, cache compression + paging + search, todos CRUD + filtering + search, context index add/get/by-tags/search, sessions + events, cross-process visibility, and input validation.

License

MIT