whimsicality-db

Un diario de trabajo para agentes de larga duración. Servidor MCP respaldado por SQLite con seguimiento de sesiones, registro de eventos y búsqueda FTS5, para que los agentes que trabajan en múltiples ventanas de contexto puedan recordar decisiones, buscar eventos pasados y realizar un seguimiento de su propio progreso.

Por qué existe esto

Los agentes que realizan trabajos de largo alcance tienen un problema: cuando la ventana de contexto se llena, pierden la noción de lo que decidieron, lo que probaron y lo que queda por hacer. El historial de conversación se desplaza y el agente vuelve a derivar conclusiones que ya había alcanzado.

whimsicality-db resuelve esto con un diario de trabajo persistente:

1. Crea una sesión para la tarea: db_session_create({ id: "refactor-auth", name: "Refactor auth system" })

2. Registra eventos a medida que ocurren: db_event_log({ session_id: "refactor-auth", event_type: "decision", content: "Chose JWT over session cookies for stateless auth" })

3. Busca decisiones pasadas: db_search({ query: "auth decision", collections: ["events"] })

4. Realiza un seguimiento de las tareas pendientes entre ventanas de contexto: db_todo_add({ title: "Implement JWT verification", session_id: "refactor-auth" })

Cuando el agente regresa después de un reinicio de la ventana de contexto, busca en el registro de sesión y continúa donde lo dejó, sin tener que releer toda la conversación.

Related MCP server: MCP Tools

Inicio rápido

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

Los datos se almacenan en ~/.whimsicality/db-storage/whimsicality.db (SQLite, modo WAL). Establece WHIMSICALITY_DB_DIR para anularlo.

Migración desde whimsicality-mcp

Si usaste el paquete obsoleto whimsicality-mcp, importa tus datos:

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

Importa entradas de memoria, documentos y fragmentos de caché comprimidos en la tabla de entradas unificada.

Herramientas (21 en total, ~2,700 tokens de esquema)

Memoria — hechos clave-valor (4)

Entradas — almacén de texto unificado con compresión automática (5)

Reemplaza las antiguas colecciones de docs, cache y context. El texto pequeño se almacena tal cual y se indexa con FTS5. El texto grande (>64KB) se comprime automáticamente con brotli y se pagina al leer. Las etiquetas y la fuente son opcionales.

Tareas pendientes — seguimiento de tareas entre ventanas de contexto (4)

Sesiones — contenedores de tareas de largo alcance (3)

Eventos — registro de sesión (2)

Búsqueda + estadísticas + importación (3)

Arquitectura

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

Búsqueda unificada

db_search({ query, collections, top_k }) busca en memoria, entradas, tareas pendientes y eventos en una sola llamada. Los resultados se fusionan y clasifican por puntuación BM25 (mayor = mejor). Cada resultado incluye su colección, ID, puntuación y un extracto centrado en la coincidencia cuando corresponde.

Compresión automática

Las entradas de más de 64KB se comprimen automáticamente con brotli. El título/resumen se almacena como texto plano para la indexación FTS5. db_entry_read descomprime bajo demanda con paginación offset+length.

Nota sobre el módulo nativo

Este paquete depende de better-sqlite3, un complemento nativo de Node.js. npm install normalmente encuentra binarios precompilados automáticamente. Si no, node-gyp compila desde el código fuente; necesitarás Python 3 y un compilador de C++. Node 22.5+ incluye node:sqlite con FTS5 integrado, que es una futura ruta sin dependencias.

Migraciones de esquema

La tabla schema_version realiza un seguimiento de la versión del esquema de la base de datos. Al abrir, el servidor lee la versión y aplica las migraciones secuencialmente: v1→v2 (tablas de unión de etiquetas), v2→v3 (tabla de entradas unificada que fusiona docs/cache/context).

Cuándo usar cada colección

• Memoria: pares clave-valor pequeños que quieras recuperar por clave exacta (hechos, configuración)

• Entradas: cualquier contenido de texto — documentos, referencias, contenido grande. Compresión automática, etiquetas opcionales, lecturas paginadas

• Tareas pendientes: tareas que el modelo está siguiendo entre ventanas de contexto

• Sesiones: contenedores de tareas de largo alcance (agrupan eventos y tareas pendientes)

• Eventos: registro cronológico dentro de una sesión (decisiones, hitos, errores)

Configuración

Desarrollo

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

67 pruebas: 64 en proceso (almacenamiento, búsqueda, entradas, tareas pendientes, sesiones, eventos, validación, importación) + 3 pruebas de humo de bin (ejecuta el punto de entrada real bin/whimsicality-db.js).

Licencia

MIT