whimsicality-db

Ein Arbeitstagebuch für langlebige Agenten. SQLite-basierter MCP-Server mit Sitzungsverfolgung, Ereignisprotokollierung und FTS5-Suche – damit Agenten, die über mehrere Kontextfenster hinweg arbeiten, Entscheidungen abrufen, vergangene Ereignisse durchsuchen und ihren eigenen Fortschritt verfolgen können.

Warum es das gibt

Agenten, die langfristige Arbeiten durchführen, haben ein Problem: Wenn das Kontextfenster voll wird, verlieren sie den Überblick darüber, was sie entschieden haben, was sie versucht haben und was noch zu tun ist. Der Gesprächsverlauf scrollt aus dem Blickfeld, und der Agent leitet Schlussfolgerungen erneut ab, die er bereits gezogen hat.

whimsicality-db löst dies mit einem persistenten Arbeitstagebuch:

1. Erstellen Sie eine Sitzung für die Aufgabe: db_session_create({ id: "refactor-auth", name: "Refactor auth system" })

2. Protokollieren Sie Ereignisse, wenn sie auftreten: db_event_log({ session_id: "refactor-auth", event_type: "decision", content: "Chose JWT over session cookies for stateless auth" })

3. Suchen Sie nach vergangenen Entscheidungen: db_search({ query: "auth decision", collections: ["events"] })

4. Verfolgen Sie Todos über Kontextfenster hinweg: db_todo_add({ title: "Implement JWT verification", session_id: "refactor-auth" })

Wenn der Agent nach einem Zurücksetzen des Kontextfensters zurückkehrt, durchsucht er das Sitzungsprotokoll und setzt dort fort, wo er aufgehört hat – ohne die gesamte Konversation erneut zu lesen.

Related MCP server: MCP Tools

Schnellstart

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

Die Daten werden unter ~/.whimsicality/db-storage/whimsicality.db gespeichert (SQLite, WAL-Modus). Setzen Sie WHIMSICALITY_DB_DIR, um dies zu überschreiben.

Migration von whimsicality-mcp

Wenn Sie das veraltete Paket whimsicality-mcp verwendet haben, importieren Sie Ihre Daten:

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

Importiert Speichereinträge, Dokumente und komprimierte Cache-Blöcke in die einheitliche Eintragstabelle.

Tools (21 insgesamt, ~2.700 Schema-Tokens)

Speicher — Schlüssel-Wert-Fakten (4)

Einträge — einheitlicher Textspeicher mit automatischer Komprimierung (5)

Ersetzt die alten Sammlungen für Dokumente, Cache und Kontext. Kleiner Text wird unverändert gespeichert und FTS5-indiziert. Großer Text (>64KB) wird automatisch mit Brotli komprimiert und beim Lesen seitenweise geladen. Tags und Quelle sind optional.

Todos — Aufgabenverfolgung über Kontextfenster hinweg (4)

Sitzungen — Container für langfristige Aufgaben (3)

Ereignisse — Sitzungsprotokoll (2)

Suche + Statistiken + Import (3)

Architektur

┌──────────────────────────────────────────────────────────┐
│ 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).                  │
└──────────────────────────────────────────────────────────┘

Einheitliche Suche

db_search({ query, collections, top_k }) durchsucht Speicher, Einträge, Todos und Ereignisse in einem Aufruf. Die Ergebnisse werden zusammengeführt und nach BM25-Score sortiert (höher = besser). Jedes Ergebnis enthält seine Sammlung, ID, Score und gegebenenfalls einen auf den Treffer zentrierten Auszug.

Automatische Komprimierung

Einträge über 64KB werden automatisch mit Brotli komprimiert. Der Titel/die Zusammenfassung wird als Klartext für die FTS5-Indizierung gespeichert. db_entry_read dekomprimiert bei Bedarf mit offset+length-Seitenweise.

Hinweis zum nativen Modul

Dieses Paket hängt von better-sqlite3 ab, einem nativen Node.js-Addon. npm install findet normalerweise automatisch vorgefertigte Binärdateien. Falls nicht, kompiliert node-gyp aus dem Quellcode – Sie benötigen Python 3 und einen C++-Compiler. Node 22.5+ enthält node:sqlite mit integriertem FTS5, was ein zukünftiger Weg ohne Abhängigkeiten ist.

Schema-Migrationen

Die Tabelle schema_version verfolgt die Version des Datenbankschemas. Beim Öffnen liest der Server die Version und wendet Migrationen sequenziell an: v1→v2 (Tag-Join-Tabellen), v2→v3 (einheitliche Eintragstabelle, die Dokumente/Cache/Kontext zusammenführt).

Wann welche Sammlung verwenden

• Speicher: kleine Schlüssel-Wert-Paare, die Sie per exaktem Schlüssel abrufen möchten (Fakten, Konfiguration)

• Einträge: beliebiger Textinhalt – Dokumente, Referenzen, große Inhalte. Automatische Komprimierung, Tags optional, seitenweises Lesen

• Todos: Aufgaben, die das Modell über Kontextfenster hinweg verfolgt

• Sitzungen: Container für langfristige Aufgaben (gruppieren Ereignisse und Todos)

• Ereignisse: chronologisches Protokoll innerhalb einer Sitzung (Entscheidungen, Meilensteine, Fehler)

Konfiguration

Entwicklung

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

67 Tests: 64 In-Process (Speicher, Suche, Einträge, Todos, Sitzungen, Ereignisse, Validierung, Import) + 3 Bin-Smoke-Tests (starten den tatsächlichen Einstiegspunkt bin/whimsicality-db.js).

Lizenz

MIT