whimsicality-db

Рабочий журнал для долгоживущих агентов. MCP-сервер на базе SQLite с отслеживанием сессий, журналированием событий и поиском 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, ~2700 токенов схемы)

Память — пары «ключ-значение» (4)

Записи — единое хранилище текста с автоматическим сжатием (5)

Заменяет старые коллекции docs, cache и context. Небольшой текст хранится как есть и индексируется FTS5. Большой текст (>64 КБ) автоматически сжимается с помощью 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, оценку и, где применимо, фрагмент с совпадением.

Автоматическое сжатие

Записи размером более 64 КБ автоматически сжимаются с помощью brotli. Заголовок/краткое описание хранится в виде обычного текста для индексации FTS5. db_entry_read распаковывает по требованию с постраничным выводом через offset+length.

Примечание о нативном модуле

Этот пакет зависит от better-sqlite3 — нативного аддона Node.js. npm install обычно автоматически находит готовые бинарные файлы. Если нет, node-gyp компилирует из исходников — потребуются Python 3 и компилятор C++. В Node 22.5+ встроен node:sqlite с поддержкой FTS5, что является будущим путём без зависимостей.

Миграции схемы

Таблица schema_version отслеживает версию схемы базы данных. При открытии сервер читает версию и применяет миграции последовательно: 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