Simple Rick

AI 코딩 에이전트를 위한 영구 메모리.

AI 에이전트와의 모든 코딩 세션은 제로부터 시작합니다. 아키텍처를 다시 설명하고, 3주 전에 이미 내린 결정을 다시 정당화하며, 이미 한 번 고쳤던 버그를 다시 발견하게 됩니다. 대화 기록은 존재하지만, 인간도 모델도 다시 읽지 않는 텍스트의 벽일 뿐입니다.

Simple Rick은 에이전트 곁에서 그 문제를 해결하는 MCP 서버입니다. 세션에서 실제로 일어난 일을 기록하고, 임베딩이 포함된 구조화된 청크로 정규화한 다음, 청크를 그래프로 연결하고, 다음 세션이 시작될 때 관련 부분을 다시 전달합니다.

모든 것은 로컬에서 실행됩니다. 프로젝트 안의 SQLite 파일 하나만 사용하며, 외부 데이터베이스도 텔레메트리도 없습니다.

상태: 알파. 작동하고 실제로 사용되고 있지만, 거친 부분이 있습니다 — 알려진 제한 사항을 참고하세요. 인터페이스는 변경될 수 있습니다.

작동 방식

flowchart LR
    A["Claude Code<br/>PostToolUse hook"] -->|POST /api/record| B[Recorder]
    W["File watcher<br/>(chokidar)"] --> B
    B --> Q[Norm queue]
    Q --> L["Lightweight<br/>normalizer"]
    L --> D["Deep<br/>normalizer"]
    D --> E[Edge wirer]
    E --> G[("SQLite<br/>+ sqlite-vec")]
    G --> BR[Briefer]
    G --> S[Semantic search]
    G --> I[Insight engine]
    BR --> M["MCP tools<br/>→ your agent"]
    S --> M
    I --> M
    G --> U["Web UI<br/>:3777"]

파이프라인에는 두 가지가 입력됩니다. 하나는 에이전트가 수행하는 모든 도구 호출을 보고하는 훅(hook) 이고, 다른 하나는 밀리초 단위 타임스탬프로 diff를 포착하는 파일 감시자(file watcher) 입니다. 둘 다 레코더에 도달하며, 레코더는 원시 턴을 크래시로부터 안전하게 기록합니다.

백그라운드 큐는 세션을 막지 않고 그 턴들을 처리합니다. 경량 정규화기는 의도와 도메인을 저비용으로 분류하고, 심층 정규화기는 요약과 임베딩을 수행하며, 엣지 연결기는 새 청크를 관련 기존 청크에 연결합니다. 그 결과는 대화 기록이 아니라 작은 지식 그래프입니다.

다음 세션이 시작되면 브리퍼(briefer) 가 그 그래프를 읽고, 에이전트에게 백지 상태 대신 브리핑을 제공합니다.

Related MCP server: hive-memory

빠른 시작

Node.js 20+ 필요.

git clone https://github.com/good-v1be/simple-rick.git
cd simple-rick
npm install
npm run build

1. AI 프로바이더 지정

Simple Rick은 임베딩용 프로바이더 하나와 채팅 완성용 프로바이더 하나가 필요합니다. 환경에서 자동 감지하며, 먼저 일치하는 것이 우선합니다:

Anthropic에는 임베딩 모델이 없으므로 Voyage를 함께 필요로 합니다.

2. MCP 서버로 등록

프로젝트의 .mcp.json에서:

{
  "mcpServers": {
    "simple-rick": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/simple-rick/src/server/index.ts"],
      "env": {
        "PROJECT_PATH": ".",
        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
      }
    }
  }
}

3. 레코더 훅 설치

이것이 없으면 Simple Rick은 파일 변경만 볼 뿐, 에이전트가 실제로 한 일은 볼 수 없습니다. hooks/simple-rick-recorder.js를 영구적인 위치에 복사하고 ~/.claude/settings.json에서 PostToolUse 훅으로 등록하세요:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write|MultiEdit",
        "hooks": [
          { "type": "command", "command": "node /path/to/simple-rick-recorder.js" }
        ]
      }
    ]
  }
}

이 훅은 fire-and-forget 방식입니다. 에이전트를 절대 막지 않으며, Simple Rick이 실행 중이 아닐 때는 조용히 아무것도 하지 않습니다.

4. 사용하기

세션을 시작하고 simple_rick_init을 한 번 호출하여 프로젝트 컨텍스트를 시드하세요. 그 후부터는 각 세션을 simple_rick_briefing으로 열고 simple_rick_close로 닫습니다.

MCP 도구

웹 UI

서버는 또한 파이프라인을 실시간으로 보여주고 결과 그래프를 표시하는 로컬 흐름 시각화를 http://127.0.0.1:3777 에 노출합니다. 첫 실행 시 생성된 베어러 토큰으로 보호되며, 토큰이 포함된 URL은 simple_rick_briefing이 출력합니다.

REST 엔드포인트: GET /api/graph, GET /api/sessions, POST /api/record.

데이터가 저장되는 위치

모든 것은 프로젝트 안의 .simple-rick/에 있습니다:

.simple-rick/
  simple-rick.db   SQLite: sessions, turns, chunks, edges, embeddings (sqlite-vec)
  .token           bearer token for the local HTTP server (mode 0600)

Simple Rick은 첫 실행 시 .simple-rick/을 .gitignore에 추가합니다. 정규화와 임베딩을 위해 설정한 AI 프로바이더 외에는 어디에도 데이터를 보내지 않습니다.

크기에 유의하세요. 전체 기록은 디스크를 적지 않게 사용합니다 — 며칠에 걸친 대규모 프로젝트는 수백 메가바이트에 달하는 데이터베이스를 만들 수 있습니다.

개발

npm run dev     # tsx watch
npm run build   # compile to dist/
npm run lint    # tsc --noEmit
npm test        # vitest (11 unit + integration tests)

또한 e2e/에는 서버를 대상으로 실제 Claude Code CLI 세션을 구동하여 모든 MCP 도구를 실행하는 엔드투엔드 스위트가 있습니다:

python3 e2e/test_mcp_e2e.py        # requires the `claude` CLI and a configured provider

실제 API 호출 비용이 들기 때문에 npm test에는 연결되어 있지 않습니다.

튜닝

모두 선택 사항입니다 — 기본값은 이 프로젝트가 수개월 동안 사용해 온 값입니다.

알려진 제한 사항

아무도 놀라지 않도록 솔직하게 정리했습니다:

• Claude Code에서만 테스트됨. MCP 인터페이스는 표준이지만, 레코더 훅은 Claude Code의 훅 형식에 맞춰 작성되었습니다.

• 기록은 디스크를 적지 않게 사용합니다. 데이터가 저장되는 위치를 참고하세요.

• 지식 그래프는 그 뒤에 있는 모델만큼만 좋을 수 있습니다. 정규화, 도메인 라우팅, 인사이트 검증은 모두 LLM 호출이며, 작거나 저렴한 모델은 그에 상응하여 모호한 그래프를 만듭니다.

• 아직 정리(pruning)가 없습니다. 데이터베이스에서 오래된 데이터가 자동으로 사라지지 않습니다.

라이선스

MIT — LICENSE를 참고하세요.