khwan-mcp

セッションを生き延びる耐久性のあるメモリ。 Khwan（純粋な AI メモリレイヤー）を Claude Code、Claude Desktop、または任意の MCP クライアントに接続する MCP サーバー。

Khwan は決してモデルを実行しません。クライアントがモデルです。 その仕事は、重要なことを永続化し蒸留して、後でセッション内で思い出したり、サブエージェントにシードしたりできる脳を作ることです。つまり、再生されたトランスクリプトではなく、コンパクトで制限のある事実の集合です。1 つのアカウントには、分離された複数のコア（ブレイン）を保持でき、— 有料プランでは — エンドユーザーごとに分離されたサブブレインも保持できます。

トークンを節約する仕組み（節約できない場面）

い込み方を正直に説明しましょう。MCP はホストのコンテキストに追加することはできますが、ホストが既に送信するトランスクリプトを置き換えることはできません。したがって：

• 1 つのホットセッション内では節約になりません。 Claude Code は増え続ける履歴をキャッシュするため（キャッシュ読み込みは約 0.1×）、毎ターン記憶を注入し直すと増えるだけです。ここではそのループを実行しないでください。

• セッションやサブエージェントをまたぐ場合は節約になります。 キャッシュは数分で消え、セッションも終わります。Khwan は蒸留した事実を永続化し、次の実行では安価に呼び出せます — 古いトランスクリプトをコールドリプレイする必要もなく、コンテキストから外れた事実も再取得できます。

トークン効率の良いパターン: キャッシングホストで毎ターンごとに完全ループを回すのではなく、一度シードして、耐久性のある事実を remember する（下記）ことをおすすめします。非キャッシングホスト上のカスタムエージェントでは、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 にリポジトリへ書き込み、設定がプロジェクトと一緒に移動します。このコマンドに含まれないものに注意してください：キーです。

リポジトリにキーを入れない

claude mcp add -e KHWAN_API_KEY=… は、リテラル値を .mcp.json に書き込みます。そのファイルの本来の目的はコミットされることです。回避策は 2 つ、2 つ目がどこでも機能します。

シェル環境変数。 KHWAN_API_KEY を設定に一切含めず、claude を起動するシェルでエクスポートしてください。サーバーはそれを継承します。

export KHWAN_API_KEY=kwk_live_xxx

ランチャー（デスクトップアプリでも機能）。 デスクトップアプリはログインシェルではなく Dock やメニューから起動されるため、シェルのエクスポートは一切継承されません。上記の方法ではキーが得られません。代わりにファイルから読み取ってください：

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 は安全にコミットでき、新しいリポジトリごとに、キーを貼り付ける代わりに 2 行を追加するだけで済みます。チームの他のメンバーもそれぞれ自分の ~/.khwan/env を書きます。

プロジェクトごとに 1 つの脳

メモリが役立つのは、正しいプロジェクトのメモリが戻ってくる場合だけです。2 つの軸があり、どちらも完全な分離を提供します：

サブブレインはフィルタではなく、完全に別のブレインです：account::acme::@Web は account::acme::@Api と何も共有しません。つまり、複数のリポジトリを持つクライアントでは、リポジトリごとに 1 つのコアを持つのではなく、1 つのコアと各リポジトリ用のサブブレインを持てます：

# 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

コアは、参照する前に存在していなければなりません — 存在しないコアは 404 を返します。コアはダッシュボードで必要あります。サブブレインは最初の書き込み時に作成されます。

推奨パターン（トークン効率型）

キャッシュホストのように Claude Code では、毎ターンのループよりも seed + remember が優先です：

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 では解決できない場合があります。アプリ全体のために 1 つのコアが選択されます — プロジェクトごとに切り替える設定はないので、広範囲のコアを選んでください。

設定（環境変数）

ツール

khwan_recall / khwan_remember は、キャッシュへの時間を予測する際のトークン節約型のペアです。khwan_prepare / khwan_record は、カスタムエージェント用のフルループです（prepare で取得した turn_token を正確に record に渡してください）。

返る内容と空回答の意味について

khwan_recall は最大3 つの事実を返しますが、この上限はサーバー側のものなので、limit は低くすることはできますが上げることはできません — また、その多くを節約することもできません。lessons は seed_text の先に送られます。つまり：数ヶ月にわたって蓄積されたなルールは、インデックスでたまたま近くに位置する単一のターンよりも優先されます。

検索には関連性の下限があります。em現し、**空のfacts` は「解答」です**： brain はこの質問に近い内容を肝持していません。失敗としてではなく、「ここでは知られていない」として読み取り、たまたま近くにあった事実を合わせて埋め合わせをしてはなりません。

下限は意図的に緩く設定しています。誤って外したメモリは目に見えない一方、誤って保持されたメモリは見えるからです。返ってきた事実が確実に関連するわけではなく、もっともらしく関連していることを期待してください — 依存する前に確認してください。

すでに、作成した内容からブレインにシードする

新しいブレインは何も知らないため、最初の数週間は検索結果が曇りました — 一方で、答えは多くの場合、ホスト自身のトランスクリプトの中にまだ読まれずに戻っています。 examples/backfill/ は、Claude Code のトランスクリプトをブレインに再生します：決定的、モデル呼び出しなし、デフォルトは dry-run。

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

常時オンのメモリ（Claude Code hooks）

上記のツールは Claude が決定したと呼び出されます。決定的なメモリ（モデルに依存しない）を求める場合は、examples/claude-code-hooks/ のフックセットを使います。UserPromptSubmit フックが各プロンプトにメモリを注入して、Stop フックが各回答を記録します。

⚠️ キャッシ・ホストでは、これは 徹底 した選択肢であり、低コスト な選択肢ではありません — ターンごとのトークンが追加されます。リコールの信頼性がトークンよりも重要な場合（または非キャッシングクライアント）に適しています。それ以外はセッション時に行う内容を khwan_recall でも実行にしてください。

ソース

github.com/khwanlabs/khwan-mcp — このサーバーは、あなたのマシン上で、あなたのキーで、あなたが入力した内容を読み取って動きます。インストールする前に必ず読んでください。

ライセンス

MIT — © Khwan Labs。 LICENSE を参照。