keephaven-mcp

keephaven-mcp

エージェントのメモリを、自宅のボックスに保存します。AI エージェントの長期メモリを、ベンダーのサーバーではなく Keephaven に保存する MCP サーバーです。

Claude Desktop、Claude Code、Cursor など、ローカルサーバーを実行する MCP クライアントで動作します。

エージェントが利用できる機能

ツール	機能
memory_write	people/dafarus.md や projects/keephaven.md のようなファイルを保存します。オプションで etag を確認し、2 つのセッションが互いの変更を上書きしないようにできます。
memory_read	etag とともにファイルを読み取ります。
memory_list	ファイルの一覧を表示します。フォルダー内に限定することもできます。
memory_search	ファイルとジャーナルを大文字・小文字を区別せずに検索します。
memory_delete	ファイルを削除します。
journal_append	追記専用のジャーナルにエントリーを追加します。エージェントは追加できますが、編集や削除はできません。
journal_read	最近のジャーナルエントリーを古い順に読み取ります。
memory_status	名前、読み取り専用かどうか、使用済みクォータを表示します。

所有者が保持できる制御

• 各エージェントには専用フォルダーが割り当てられ、ほかのエージェントのフォルダーを見ることはできません。
• Keephaven の Settings > Agents でエージェントを追加すると、トークンが発行されます。トークンは一度だけ表示され、ボックスにはフィンガープリントのみが保存されます。
• トークンを取り消すと、エージェントは直ちにアクセスできなくなります。ファイルは削除するまで残ります。
• エージェントごとにサイズ上限を設定するか、読み取り専用にできます。
• Keephaven のバックアップ先として 2 台目のボックスを設定している場合、エージェントのフォルダーもバックアップされ、バックアップ先のボックスではすべての削除が拒否されます。この機能は、実機 2 台の間ではまだテストされていません。

セットアップ

1. Keephaven で、Settings > Agents > Add an agent を選択します。表示された 2 つの値をコピーします。
2. MCP クライアントにサーバーを追加します。Claude Desktop の場合は、claude_desktop_config.json に次のように記述します。

{
  "mcpServers": {
    "keephaven": {
      "command": "npx",
      "args": ["-y", "github:dafarusd/keephaven-mcp"],
      "env": {
        "KEEPHAVEN_URL": "http://keephaven-xxxx.local:8790",
        "KEEPHAVEN_TOKEN": "khm_..."
      }
    }
  }
}

Claude Code の場合：

claude mcp add keephaven -e KEEPHAVEN_URL=http://keephaven-xxxx.local:8790 -e KEEPHAVEN_TOKEN=khm_... -- npx -y github:dafarusd/keephaven-mcp

GitHub から直接インストールするため、ビルドに少し時間がかかり、初回の起動には 1 分ほどかかります。Node 20 以降が必要です。

エージェントを実行するマシンからボックスにアクセスできる必要があります。同じホームネットワーク、Keephaven 自身の Wi-Fi、またはリモートアクセスが有効な場合の Tailscale tailnet を使用してください。

ボックスなしで試す

ボックスは依存関係のない Python ファイルを 1 つ実行します。同じファイルを Python 3 でどこでも実行できます。

python3 agent-memory.py serve --data ./mem --bind 127.0.0.1 --dev-token khm_try-it-locally

その後、トークンを指定して MCP サーバーの接続先を http://127.0.0.1:8790 に設定します。このファイルは Keephaven リポジトリ内の modules/agent-memory.py です。

現状について、ありのままに

• メモリサービスは実装済みで、テストも完了しています。API テスト 22 件と、サービスが専用の制限されたユーザーとして動作し、2 台目のマシンがネットワーク経由で利用する 2 台の VM による NixOS テストを実施しました。
• この MCP サーバーには、エンドツーエンドテストが 7 件あります。公式 MCP クライアント、このサーバーを介した stdio 通信、実際のメモリサービスを使用しています。
• Keephaven Agent Memory に同梱され、2026-10-25 に Pi 5 向け、および Windows PC 上の USB SSD 向けにリリースされました：https://keephaven.co/agent-memory。Pi 版は 1 台の Pi 5 で、SSD 版は Windows PC 上の実ドライブでリリースチェックに合格しました。バックアップは実際の Pi 5（リリース前ビルド）から、Tailscale 経由で VM 内の PC ビルドに対して実行しました。ただし、実機 2 台の間ではまだテストされていません。 Home および Photos の各ボックスには搭載されていません。
• トークンはホームネットワーク上では、ボックスのほかのローカルページと同様に暗号化されていない HTTP で送信されます。Tailscale 経由では暗号化されます。

エージェントスキル

skill/keephaven/ はエージェントスキルです（SKILL.md と読み取り専用の check.py で構成）。Keephaven をメモリとして使用する方法と、VM で起動して動作状況を報告する方法を説明します。check.py は QEMU で起動した Photos の SSD イメージに対して実行されました。セットアップページの表示後、準備完了となり、Photos が起動し、Immich 3.0.3 が動作しました。

@Dafarusd が開発しました。MIT License。