Khwan

khwan-mcp

セッションを超えて保持される永続メモリ。 Khwan — 純粋な AI メモリレイヤー — を Claude Code、Claude Desktop、または任意の MCP クライアントに接続する MCP サーバーです。

Khwan が実行するのは、あなたのモデルではありません。モデルはクライアントです。 Khwan の役割は、重要な情報を保存して要約し、後のセッションで呼び出したり、サブエージェントに与えたりできる脳にすることです。再生された会話の文字起こしではなく、コンパクトで上限のある事実の集合です。1 つのアカウントに、分離された複数のコア（脳）を保持でき、有料プランではエンドユーザーごとに独立したサブ脳を持てます。

読み取りでも書き込みでも、推論呼び出しのコストはかかりません。khwan_recall と khwan_remember は推論呼び出しを行いません。Khwan は独自のモデルを 1 つ、スケジュールに従って実行します。保存された会話を恒久的な教訓へ要約する夜間処理です。実際の本番環境での実行では、8 個の脳と保存された 245 件の会話から 11 件の教訓が要約され、$0.0094かかりました。この処理のコストは Khwan が負担するもので、あなたにはかかりません。これが、毎回のターンで圧縮、グラフ化、統合を行うメモリレイヤーとの決定的な違いです。

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

仕組みについて正直に説明します。MCP はホストのコンテキストに追加するものであり、ホストがすでに送信している会話の文字起こしを置き換えることはできません。そのため、次のようになります。

• 同じアクティブなセッション内では、トークンを節約しません。 Claude Code は増え続ける履歴をキャッシュします（キャッシュ読み取りは約 0.1 倍）。そのため、毎回のターンでメモリを再注入すると、追加コストがかかるだけです。ここではそのような使い方はしないでください。
• セッション間やサブエージェント間では、節約できます。 キャッシュは数分で消え、セッションは終了します。Khwan は要約した事実を保持するため、次の実行ではコストを抑えて呼び出せます。古い会話の文字起こしを最初から再生する必要はなく、コンテキストから流れて消えた事実も再取得できます。

トークンを賢く使うパターンは、キャッシュするホストで毎回すべての処理を実行するのではなく、一度だけ与え、長期的に役立つ事実を記憶させることです（以下を参照）。prepare → record の完全なループは、履歴を要約メモリに置き換えてターンごとのコストを直接抑えられる、キャッシュしないホスト上のカスタムエージェントでこそ効果を発揮します。

インストール

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

ランチャー（デスクトップアプリでも動作します）。 デスクトップアプリはログインシェルではなく、ドックやメニューから起動するため、シェルでエクスポートした環境変数を引き継ぎません。そのため、上記の方法ではキーが設定されず、気付かないまま動作しません。代わりにファイルから読み込みます。

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つの軸があり、どちらも完全に分離されています。

	選択方法	無料	有料
コア	KHWAN_CORE	1 — default のみ	5（starter）→ 25（pro）
サブブレイン	KHWAN_USER	3	無制限

サブブレインはフィルターではなく、完全に独立した脳です。account::@web は account::@api と何も共有しません。つまり、2つの軸は掛け合わせられ、無料アカウントでも、コア単体に加えて3つのサブブレイン、合計4つの独立した脳を保持できます。

account              default core, no KHWAN_USER      brain 1
account::@web        KHWAN_USER=web                   brain 2
account::@api        KHWAN_USER=api                   brain 3
account::@docs       KHWAN_USER=docs                  brain 4

つまり、無料プランでも、最大4つのプロジェクトでプロジェクトごとに1つの脳を使えます。しかも、KHWAN_CORE は不要です。

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

名前付きコアは有料の軸です。4つでは足りなくなったときや、リポジトリごとではなくクライアントごとにまとめたいときに利用してください。

# 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

KHWAN_CORE を設定する前に知っておくべきことが2つあります。コアはあらかじめ作成しておく必要があります。不明なスラッグに対しては 404 が返され、「作成しました」という応答にはなりません。コアはダッシュボードで作成します。無料プランでは、指定できるコアがありません。上限の1つは default で使用済みなので、名前付きコアを作成しようとすると 402 が返されます。無料プランでは KHWAN_CORE を設定せず、KHWAN_USER を使用してください。一方、サブブレインは初回の書き込み時に作成されます。

おすすめのパターン（トークンを節約）

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 だけでは見つからない場合があります。アプリ全体で使用するコアは1つ選択されます。この設定ではプロジェクトごとに切り替えられないため、幅広く使えるものを選んでください。

設定（環境変数）

変数	必須	用途
KHWAN_API_KEY	はい	Khwan ダッシュボードで取得したキー（kwk_live_…）。
KHWAN_CORE	いいえ	名前付きコアを選択します。有料プランのみ。無料プランでは default のみです。
KHWAN_USER	いいえ	コア内の独立した脳。無料プランでは3つ、有料プランでは無制限です。
KHWAN_BASE_URL	いいえ	API のベース URL を上書きします。例：ローカルエンジンの場合は http://127.0.0.1:8010。

ツール

ツール	使用するタイミング
khwan_recall(query, limit=3)	セッション／サブエージェントにシードを与えます。統合されたlessonsと、関連性の高い最大3件の事実をseed_textとして返します。
khwan_remember(fact)	将来のセッションのために、長期的に有用な事実／設定を保存します。
khwan_prepare(input)	回答前に、メモリーのコンテキストとturn_tokenを含む一連の処理を実行します。
khwan_record(turn_token, answer)	回答後に、そのターンを保存してKhwanが学習できるよう、一連の処理を実行します。
khwan_memory(limit=20)	現在、メモリーが記憶している内容を確認します。
khwan_cores()	アカウント上の分離されたコアを一覧表示します。

khwan_recall／khwan_rememberは、キャッシュ対応ホスト向けのトークン効率の良いペアです。 khwan_prepare／khwan_recordは、カスタムエージェント向けの一連の処理です（prepareから返された 正確なturn_tokenをrecordに渡してください）。

返される内容と、回答が空の場合の意味

khwan_recallが返す事実は最大3件です。この上限はサーバー側で設定されているため、 limitで減らすことはできますが、増やすことはできません。また、多数の過去のターンから 抽出されたlessonsの統合内容も返されます。seed_textではLessonsが先頭に来ます。何か月もかけて 得られたルールは、インデックス上でたまたま近くにある単一のターンより優先されます。

検索には関連性のしきい値が適用されるため、factsが空でも、それ自体が回答です。 つまり、この質問に近い内容はメモリーにありません。「ここでは分からない」と受け止め、 最も近かった事実に頼って不足分を埋めないでください。

このしきい値は意図的に低めに設定されています。誤って破棄されたメモリーは見えませんが、 誤って保持されたメモリーは見えるためです。返された事実は、確実に関連しているというより、 関連している可能性があるものと考えてください。頼る前に内容を確認してください。

すでに行った作業からメモリーを作成する

新しいメモリーには何も蓄積されていないため、最初の数週間は検索結果が乏しくなります。 その一方で、答えはホスト自身の未読のトランスクリプトにすでに残っていることがよくあります。 examples/backfill/はClaude Codeのトランスクリプトをメモリーに再生します。 決定的に実行され、モデル呼び出しはなく、デフォルトではドライランです。

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

常時有効なメモリー（Claude Codeフック）

上記のツールは、Claudeが判断したときに呼び出されます。モデルに依存しない 決定的なメモリーには、 examples/claude-code-hooks/のフックプリセットを使用してください。 UserPromptSubmitフックはすべてのプロンプトにメモリーを注入し、Stopフックはすべての回答を記録します。

⚠️ キャッシュ対応ホストでは、これは低コストな方法ではなく、徹底的な方法です。 ターンごとにトークンが追加されます。トークンコストよりも検索の信頼性が重要な場合 （またはキャッシュ非対応のクライアントを使う場合）に適しています。それ以外の場合は、 セッション開始時にkhwan_recallを使用してください。

ソース

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

ライセンス

MIT — © Khwan Labs。LICENSEを参照してください。