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. 컨텍스트 창 간 할 일 추적: 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" })

메모리 항목, 문서, 압축된 캐시 청크를 통합 entries 테이블로 가져옵니다.

도구 (총 21개, 스키마 약 2,700 토큰)

메모리 — 키-값 사실 (4)

항목 — 자동 압축이 포함된 통합 텍스트 저장소 (5)

기존의 docs, cache, context 컬렉션을 대체합니다. 작은 텍스트는 그대로 저장되고 FTS5로 인덱싱됩니다. 큰 텍스트(64KB 초과)는 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, 점수, 그리고 해당되는 경우 일치 항목 중심의 발췌문이 포함됩니다.

자동 압축

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를 병합한 통합 entries 테이블).

어떤 컬렉션을 언제 사용할까

• 메모리: 정확한 키로 불러오고 싶은 작은 키-값 쌍(사실, 설정)

• 항목: 모든 텍스트 콘텐츠 — 문서, 참조 자료, 대용량 콘텐츠. 자동 압축, 선택적 태그, 페이지 단위 읽기

• 할 일: 모델이 컨텍스트 창 간에 추적하는 작업

• 세션: 장기 작업 컨테이너(이벤트와 할 일을 그룹화)

• 이벤트: 세션 내 시간순 로그(결정, 이정표, 오류)

구성

개발

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