whimsicality-mcp

AI 에이전트에 영구 메모리(세션과 프로세스를 넘어 유지되는 컨텍스트 저장, 사실, 계획, RAG 검색, 코드 스니펫, 대화 압축)를 제공하는 MCP(Model Context Protocol) 서버입니다.

MCP 호환 에이전트와 함께 작동합니다: Devin CLI, Claude Desktop, Cursor 등.

빠른 시작

# Install globally
npm install -g whimsicality-mcp

# Or run without installing
npx whimsicality-mcp

그런 다음 에이전트의 MCP 구성에 추가하세요:

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

끝입니다. 서버는 기본적으로 디스크 기반 영속성으로 즉시 작동하며, 네이티브 종속성이 필요 없습니다. 데이터는 ~/.whimsicality/kernel-storage/에 저장됩니다.

Related MCP server: Memory MCP

도구

서버는 whim_ 접두사가 붙은 14개의 도구를 노출합니다:

에이전트가 사용하는 방법

세션 시작 시 — 이전 에이전트의 상태 복구:

1. whim_plan_get({})              → read the current plan
2. whim_facts_list({})            → list all facts
3. whim_facts_get({name: "..."})  → read relevant facts
4. whim_context_list({})          → list all context slots
5. whim_context_get({key: "..."}) → read relevant slots

작업 중 — 다음 에이전트를 위한 상태 저장:

whim_plan_save({plan: "updated plan with progress and next steps"})
whim_facts_save({name: "new_fact", value: "..."})
whim_context_set({key: "what_i_learned", text: "..."})

백엔드

서버는 커널을 찾는 네 가지 방법을 순서대로 지원합니다:

1. 디스크 폴백 (기본값, 설정 불필요)

즉시 작동합니다. 데이터는 ~/.whimsicality/kernel-storage/whim-mcp-store.json의 JSON 파일에 유지됩니다. RAG/스니펫에 대한 단어 중복 검색. 네이티브 종속성이 없습니다.

2. 사전 빌드된 커널 바이너리 (가장 쉬운 업그레이드)

npm install @whimsicalitylabs/kernel-prebuilt

npm optionalDependencies를 통해 배포되는 플랫폼별 사전 빌드 바이너리. 서버는 node_modules에서 바이너리를 자동으로 찾습니다.

참고: 사전 빌드된 바이너리가 아직 모든 플랫폼에서 제공되는 것은 아닙니다. 상태는 kernel-prebuilt를 참조하세요.

3. 기존 바이너리 가리키기

{
  "mcpServers": {
    "whimsicality": {
      "command": "npx",
      "args": ["whimsicality-mcp"],
      "env": {
        "WHIMSICALITY_KERNEL_BIN": "/path/to/whimsicality-kernel"
      }
    }
  }
}

4. 소스에서 빌드

Rust 워크스페이스를 클론하고 빌드하세요:

git clone https://github.com/WhimsicalityLabs/whimsicality-kernel.git
cd whimsicality-kernel
cargo build --release

그런 다음 WHIMSICALITY_KERNEL_BIN을 target/release/whimsicality-kernel로 설정하세요.

커널이 추가하는 것

Rust 커널은 다음을 제공합니다:

• 계층형 스토리지: 핫(RAM) → 웜(mmap) → 콜드(디스크의 zstd) 및 자동 승격/강등

• 콘텐츠 주소 지정 중복 제거: blake3 해싱을 통한 동일 값 공유 저장

• 잠금 없는 핫 경로: 동시 읽기를 위한 DashMap

• 추가 전용 세션 로그: 분기/포크가 가능한 bincode 항목

• 구조화된 컨텍스트 어셈블리: 평면 토큰 스트림이 아닌 명명된 변수

커널을 사용할 수 있으면 서버는 커널과 디스크 양쪽에 이중 쓰기를 수행합니다. 이를 통해 커널의 빠른 세션 내 액세스와 교차 세션 안정성을 위한 디스크 영속성을 모두 얻을 수 있습니다(커널의 핫 계층은 RAM 전용이며 프로세스 종료 시 손실됨).

구성

모든 구성은 환경 변수를 통해 이루어집니다:

개발

git clone https://github.com/WhimsicalityLabs/Whimsicality-MCP.git
cd whimsicality-mcp
npm install
npm run build
node bin/whimsicality-mcp.js

라이선스

MIT