khwan-mcp

세션이 끝나도 유지되는 지속성 메모리. MCP 서버가 Khwan — 순수한 AI 메모리 레이어 — 을 Claude Code, Claude Desktop, 또는 모든 MCP 클라이언트에 연결합니다.

Khwan은 모델을 실행하지 않습니다. 클라이언트가 곧 모델입니다. Khwan의 역할은 중요한 것을 저장하고 정제해서, 나중 세션에서 다시 기억하거나 서브에이전트의 시드로 사용할 수 있는 뇌로 만드는 것입니다. 재생되는 대화 기록이 아니라, 압축되고 한계가 분명한 사실 묶음입니다. 계정 하나에는 격리된 여러 개의 core(브레인)가 담길 수 있고, 유료 플랜에서는 최종 사용자별 격리된 서브 브레인도 둘 수 있습니다.

토큰을 절약하는 방법 (그리고 절약되지 않는 경우)

메커니즘을 솔직하게 말하면, MCP는 호스트의 컨텍스트에 추가할 뿐이며 호스트가 이미 전송하는 대화 기록을 대체할 수 없습니다. 그러므로:

• 열려 있는 하나의 세션 안에서는 토큰을 절약하지 못합니다. Claude Code는 점점 커지는 히스토리를 캐시하므로(캐시 읽기 ≈ 0.1×), 매 턴마다 메모리를 다시 주입하는 것은 용량만 늘릴 뿐입니다. 여기서 그렇게 하지 마세요.

• 세션 사이와 서브에이전트 사이에서는 절약합니다. 캐시는 수 분 안에 만료되고, 세션은 끝납니다. Khwan은 정제된 사실을 영구히 저장하므로 다음 실행이 저렴하게 그것들을 다시 가져올 수 있습니다 — 이전 기록을 처음부터 다시 재생할 필요가 없고, 이미 컨텍스트에서 벗어난 사실도 다시 찾을 수 있습니다.

토큰 스마트한 패턴: 캐싱 호스트의 매 턴마다 전체 루프를 실행하는 대신, 한 번 시드하고 지속성 있는 사실을 기록하세요(아래 참조). 전체 prepare → record 루프는 여전히 비캐싱 호스트의 커스텀 에이전트에서 빛을 발합니다. 거기서는 기록을 정제된 메모리로 대체해 턴당 비용을 직접 경계 지어 줍니다.

Related MCP server: LedgerMem MCP Server

설치

pip install khwan-mcp          # or: uvx khwan-mcp

Claude Code에 연결

claude mcp add khwan --scope project \
  -e KHWAN_CORE=default \
  -- khwan-mcp

--scope project는 .mcp.json을 저장소 안에 작성하므로, 설정이 프로젝트와 함께 이동합니다. 이 명령에 없는 것이 무엇인지 눈여겨보세요: 바로 키(key)입니다.

키를 저장소에서 분리하기

claude mcp add -e KHWAN_API_KEY=…는 그 리터럴 값을 .mcp.json에 기록합니다. 그런데 그 파일은 커밋되는 게 목적인 파일입니다. 이를 피하는 방법은 두 가지이고, 두 번째가 어디에서나 동작하는 방법입니다.

셸 환경. KHWAN_API_KEY를 설정에 전혀 넣지 말고, claude를 실행하는 셸에서 내보냅니다. 서버가 그 값을 상속합니다.

export KHWAN_API_KEY=kwk_live_xxx

런처(데스크톱 앱에서도 동작). 데스크톱 앱은 로그인 셸이 아니라 독이나 메뉴에서 시작되므로, 여러분의 셸 내보내기를 하나도 상속하지 않으며, 위 방식은 조용히 키가 없는 상태가 됩니다. 대신 파일에서 키를 읽게 만드세요:

mkdir -p ~/.khwan && chmod 700 ~/.khwan
printf 'KHWAN_API_KEY=kwk_live_xxx\n' > ~/.khwan/env && chmod 600 ~/.khwan/env

cat > ~/.khwan/khwan-mcp <<'SH'
#!/bin/sh
set -a
[ -f "$HOME/.khwan/env" ] && . "$HOME/.khwan/env"
set +a
exec khwan-mcp "$@"
SH
chmod 700 ~/.khwan/khwan-mcp

그런 다음 설정을 런처를 가리키도록 바꾸고, 비밀이 아닌 값만 인라인으로 남겨 두세요:

claude mcp add khwan --scope project \
  -e KHWAN_CORE=acme -e KHWAN_USER=Web \
  -- ~/.khwan/khwan-mcp

이제 .mcp.json은 커밋해도 안전하며, 새 저장소마다 키 복사 붙여넣기 대신 두 줄만 필요합니다. 팀의 다른 사람은 각자 자신의 ~/.khwan/env를 만들어 쓰면 됩니다.

프로젝트마다 하나의 브레인

메모리는 이 프로젝트의 메모리가 돌아와야만 쓸모가 있습니다. 축이 두 가지이며, 둘 다 완전한 격리를 제공합니다:

서브 브레인은 필터가 아니라 완전히 분리된 브레인입니다: account::acme::@Web은 account::acme::@Api와 아무것도 공유하지 않습니다. 따라서 여러 저장소를 사용하는 클라이언트는 core를 저장소마다처럼 두지 않고, 하나의 core 안에 저장소별 서브 브레인 하나씩 두면 됩니다:

# in ~/code/acme-web
claude mcp add khwan --scope project -e KHWAN_CORE=acme -e KHWAN_USER=Web -- ~/.khwan/khwan-mcp
# in ~/code/acme-api
claude mcp add khwan --scope project -e KHWAN_CORE=acme -e KHWAN_USER=Api -- ~/.khwan/khwan-mcp

core는 지정하기 전에 반드시 존재해야 합니다 — 존재하지 않는 core는 404를 반환합니다. 대시보드에서 생성하세요. 서브 브레인은 첫 쓰기 때 생성됩니다.

권장 패턴 (토큰 스마트형)

Claude Code 같은 캐싱 호스트에서는 매 턴 루프보다 시드 + 기억하기를 선호하세요:

1. 시드 — 세션이나 서브에이전트 시작 시:

   "khwan_recall(query="<the task>")를 호출하고, 반환된 seed_text를 컨텍스트로 사용하세요."

2. 기억 — 지속해야 할 사실이 드러나면:

   "그것은 계속 유지될 결정입니다 — khwan_remember(fact="…")를 호출하세요."

이것을 프로젝트의 CLAUDE.md에 강화해 넣으세요. 예:

- At the start of a task, call `khwan_recall` to seed relevant memory.
- When a durable decision/preference/fact emerges, call `khwan_remember`.
- Don't call prepare/record every turn — it adds tokens without saving them here.

서브에이전트 시드가 가장 효과가 분명한 곳입니다. 전체 대화 대신 한정된 브랜드를 넘겨주세요:

"khwan_recall(query="deploy runbook")로 배포 메모리를 불러온 후, 그 seed_text에 작업을 더한 브랜드를 가진 서브에이전트를 생성하세요."

Claude Desktop에 연결

Claude Desktop과 Claude Code는 별도의 MCP 설정을 유지합니다. 한쪽에 추가한 서버는 다른 쪽에 보이지 않으며, claude mcp add도 이 파일을 건드리지 않습니다. claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "khwan": {
      "command": "/Users/you/.khwan/khwan-mcp",
      "env": {
        "KHWAN_CORE": "acme",
        "KHWAN_USER": "Web"
      }
    }
  }
}

절대 경로를 사용하세요. 데스크톱 앱도 여러분의 셸 PATH를 가져오지 않으므로, 맨 khwan-mcp는 경로가 풀리지 않을 수 있습니다. 앱 전체에서 하나의 core가 선택됩니다. 이곳에는 프로젝트별 스위치가 없으므로, 폭넓은 core 하나를 골라 두세요.

구성 (환경 변수)

도구

khwan_recall / khwan_remember는 캐싱 호스트를 위한 토큰 스마트 쌍이고, khwan_prepare / khwan_record는 커스텀 에이전트를 위한 전체 루프입니다(이 정확한 turn_token 준비에서 record로 전달하세요).

무엇이 반환되며, 빈 답변이 의미하는 바

khwan_recall은 최대 세 개의 사실을 반환합니다 — 그 상한은 서버의 것이므로 limit는 낮출 수 있어도 높힐 수는 없습니다 — 그리고 많은 과거 턴에서 합성 모듈이 정제한 lessons도 함께 반환하지. lessons가 seed_text의 앞에 옵니다: 몇 달에 걸쳐 얻은 규칙이 인덱스에서 근처에 있다고 마침 우연히 지나간 한번의 턴보다 우위에 있습니다.

검색에는 관련성 하한값이 적용되므로 빈 facts도 하나의 답변입니다: 브레인에 이 질문과 가까운 내용이 없다는 뜻입니다. 그것을 실패가 아닌 "여기서는 알 수 없다"고 읽고, 가장 가까운 사실 하나에 의하지 그 빈 곳을 메우지 마세요.

그 하한값은 의도적으로 낮게 잡혀 있습니다. 잘못 버려진 기억은 발견할 수 없지만, 잘못 보관된 기억은 그렇지 않기 때문입니다. 반환된 사실이 대체로 관련되어 있다고 생각하고, 확실히 관련 있다고 생각하지 말며, 신뢰하기 전에 반드시 읽어보세요.

이미 해둔 작업으로 브레인 시드하기

새 브레인은 아무것도 모르기 때문에 처음 몇 주는 기억이 흐미합니다. 그런데 정답은 이미 호스트의 트랜스크립트 속에 읽히지 않은 채 있는 경우가 많습니다. examples/backfill/을(를) 통해 Claude Code 트랜스크립트를 브레인에 재생합니다: 결정적이며, 모델 호출이 없고, 기본적으로 dry-run입니다.

python3 examples/backfill/backfill_claude_code.py --map cores.json

항상 켜져 있는 메모리 (Claude Code hooks)

위 도구들은 Claude가 결정할 때만 호출됩니다. 모델에 의존하지 않는 결정적 메모리가 필요하다면, examples/claude-code-hooks/에 있는 hook preset을 쓰세요. UserPromptSubmit 훅이 모든 프롬트에 메모를 주입하고 Stop 훅이 모든 답변을 기록합니다.

⚠️ 캐싱 호스트에 있다면, 이것은 값음 싼 옵션이 아니라 철저한 옵션입니다. 매 턴 토큰이 늘어납니다. 토큰 책임보다 회수 신뢰성이 더 중요할 때(또는 비캐싱 클라이언트를 쓸 때) 이 방식을 우선하세요. 그렇지 않으면 세션 시작부터 khwan_recall을 사용하세요.

소스

github.com/khwanlabs/khwan-mcp — 이 서버는 여러분의 컴퓨터에서, 여러분의 키로, 여러분의 입력을 읽을 실행됩니다. 설치하기 전에 먼저 읽어 보신..

License

MIT — © Khwan Labs. LICENSE를 참조하세요.