Roampal — 成果ベースの永続メモリMCPサーバー

なぜ必要なのか？

AIコーディングアシスタントは、セッション間で何もかも忘れてしまいます。アーキテクチャや好み、規約について何度も説明しなければなりません。また、AIが誤ったアドバイスをした場合、そこから学習する仕組みもありません。

Roampalは、すべてのセッションを通じてAIに永続的な成果ベースのメモリを提供するMCPサーバーです。良いアドバイスは昇格され、悪いアドバイスは降格されます。AIはワークフローを一切変更することなく、自動的に何が有効で何がそうでないかを学習します。

ベンチマーク

LoCoMoで85.8%（非敵対的、エンドツーエンドの回答精度） — 10の会話にわたる1,986の質問で、二重評価により検証済み。

結果	スコア
会話型学習 vs 生の取り込み	+23ポイント (76.6% vs 53.0%, p<0.0001)
アーキテクチャ vs モデルの影響	アーキテクチャの方が約10倍寄与度が高い
汚染耐性（1,135の敵対的メモリ）	-2.6〜-4.2ポイントのみ
TagCascade検索（タグ優先 + CEリランク）	+1.9 Hit@1 vs 純粋なCE (p<0.0001)

ベンチマークパイプラインはクラウド依存なしで単一のGPU上で実行されます。Roampal自体はCPUで動作するため、GPUは不要です。完全な手法、データ、評価スクリプトについてはroampal-labsを参照してください。

論文: "Beyond Ingestion: What Conversational Memory Learning Reveals on a Corrected LoCoMo Benchmark" (Logan Teague, 2026年4月)

クイックスタート

pip install roampal
roampal init

インストールされているツールを自動検出します。エディタを再起動してチャットを開始してください。

特定のツールをターゲットにする場合: roampal init --claude-code または roampal init --opencode

コアとなるループは同一で、どちらのプラットフォームもコンテキストを注入し、やり取りをキャプチャし、成果をスコアリングします。配信メカニズムが異なります：

	Claude Code	OpenCode
コンテキスト注入	フック (stdout)	プラグイン (システムプロンプト)
やり取りのキャプチャ	ストップフック	プラグイン `session.idle` イベント
スコアリング	`score_memories` ツール経由のメインLLM	独立したサイドカー（選択したモデル > Zen free）
自己修復	失敗時にフックがサーバーを自動再起動	失敗時にプラグインがサーバーを自動再起動

Claude Codeは、メインLLMに対して score_memories ツール経由で各やり取りをスコアリングするよう促します。OpenCodeは自己スコアリングを行わず、独立したサイドカー（別のAPI呼び出し）が第三者として各やり取りをレビューし、自己評価のバイアスを取り除きます。score_memories ツールはOpenCodeには登録されません。roampal init または roampal sidecar setup の際、Roampalはローカルモデル（Ollama、LM Studioなど）を検出し、スコアリングモデルを選択できるようにします。設定されている場合、これらが優先されます（プライバシー保護のためZenはスキップされます）。安価なモデルやローカルモデルで十分機能します。スコアリングに強力なモデルは不要です。セットアップをスキップした場合は、Zen freeモデル（リモート、ベストエフォート）がデフォルトになります。

仕組み

メッセージを入力すると、RoampalはAIがそれを見る前に自動的に関連するコンテキストを注入します：

入力:

fix the auth bug

AIの視点:

═══ KNOWN CONTEXT ═══
• JWT refresh pattern fixed auth loop [id:patterns_a1b2] (3d, 90% proven, patterns)
• User prefers: never stage git changes [id:mb_c3d4] (memory_bank)
═══ END CONTEXT ═══

fix the auth bug

手動の呼び出しは不要です。ワークフローの変更もありません。ただ動作するだけです。

ループ

メッセージを入力
Roampalが関連コンテキストを自動注入（Claude Codeではフック、OpenCodeではプラグイン）
AIが履歴、好み、過去の成功事例を完全に把握した状態で応答
成果をスコアリング — 良いアドバイスは昇格、悪いアドバイスは降格
繰り返し — やり取りのたびにシステムが賢くなります

5つのメモリコレクション

コレクション	目的	寿命
`working`	現在のセッションコンテキスト	24時間 — 有用なら昇格、そうでなければ削除
`history`	過去の会話	30日間、成果スコアリング済み
`patterns`	実証済みの解決策	有用な限り永続、履歴から昇格
`memory_bank`	アイデンティティ、好み、目標	永続
`books`	アップロードされた参照ドキュメント	永続

コマンド

roampal init                # Auto-detect and configure installed tools
roampal init --claude-code  # Configure Claude Code explicitly
roampal init --opencode     # Configure OpenCode explicitly
roampal init --no-input     # Non-interactive setup (CI/scripts)
roampal start               # Start the HTTP server manually
roampal stop                # Stop the HTTP server
roampal status              # Check if server is running
roampal status --json       # Machine-readable status (for scripting)
roampal stats               # View memory statistics
roampal stats --json        # Machine-readable statistics (for scripting)
roampal doctor              # Diagnose installation issues
roampal summarize           # Summarize long memories (retroactive cleanup)
roampal score               # Score the last exchange (manual/testing)
roampal context             # Output recent exchange context
roampal ingest <file>       # Add documents to books collection
roampal books               # List all ingested books
roampal remove <title>      # Remove a book by title
roampal sidecar status      # Check scoring model configuration (OpenCode)
roampal sidecar setup       # Configure scoring model (OpenCode)
roampal sidecar test        # Test scoring model response format (OpenCode)
roampal retag               # Re-extract tags on memories using sidecar LLM
roampal sidecar disable     # Remove scoring model configuration (OpenCode)

MCPツール

AIは以下のメモリツールを利用できます：

ツール	説明	プラットフォーム
`search_memory`	すべてのコレクションを横断した詳細検索	両方
`add_to_memory_bank`	永続的な事実（アイデンティティ、好み、目標）を保存	両方
`update_memory`	既存のメモリを修正または更新	両方
`delete_memory`	古い情報を削除	両方
`score_memories`	前回のやり取りの成果をスコアリング	Claude Code
`record_response`	重要なやり取りからの主要な要点を保存	両方

スコアリングの仕組み: Claude Codeのフックは、メインLLMに対して毎ターン score_memories を呼び出すよう促します。OpenCodeはバックグラウンドで静かにスコアリングを行う独立したサイドカーを使用します。モデルがスコアリングプロンプトを見ることはなく、score_memories はツールとして登録されません。サイドカーが利用できない場合は、roampal sidecar setup を実行するようユーザーに警告が表示されます。roampal init または roampal sidecar setup でスコアリングモデルを選択してください。

Roampalの比較

機能	Roampal Core	Claude Code内蔵 (CLAUDE.md / 自動メモリ)	OpenCode内蔵
成果から学習	はい — 悪いアドバイスは降格、良いアドバイスは昇格	いいえ	いいえ
セマンティック検索	はい — TagCascade + クロスエンコーダーリランク	いいえ — ファイル全体を読み込み、検索なし	メモリシステムなし
コンテキスト注入	自動 — クエリごとに関連メモリを注入	セッションごとにCLAUDE.md全体、要求に応じて自動メモリ	なし
原子的な事実抽出	はい — 要約 + 事実、2レーン検索	いいえ — Claudeが有用と判断したもののみ保存	なし
プロジェクト横断	はい — すべてのプロジェクトでメモリを共有	プロジェクト単位のみ (gitリポジトリごと)	メモリなし
履歴の拡張性	はい — 5つのコレクション、昇格/降格/減衰	CLAUDE.mdは無制限、自動メモリは最初の200行	メモリなし
完全ローカル/プライベート	はい — マシン上のChromaDB	はい	はい

┌─────────────────────────────────────────────────────────┐
│  pip install roampal && roampal init                    │
│    Claude Code: hooks + MCP → ~/.claude/                │
│    OpenCode:    plugin + MCP → ~/.config/opencode/      │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  HTTP Hook Server (port 27182)                          │
│    Auto-started on first use, self-heals on failure     │
│    Manual control: roampal start / roampal stop         │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  User types message                                     │
│    → Hook/plugin calls HTTP server for context          │
│    → AI sees relevant memories, responds                │
│    → Exchange stored, scored (hooks or sidecar)         │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  Single-Writer Backend                                  │
│    FastAPI → UnifiedMemorySystem → ChromaDB             │
│    All clients share one server, isolated by session    │
└─────────────────────────────────────────────────────────┘

技術的な詳細については dev/docs/ を参照してください。

要件

Python 3.10+
次のいずれか: Claude Code または OpenCode
プラットフォーム: Windows, macOS, Linux (主にWindowsで開発・テスト済み)
RAM: 約800MBの空き容量 (クロスエンコーダーリランク + エンベディング + ChromaDB)
ディスク: モデル用に約500MB (多言語エンベディング + リランカー、初回使用時に自動ダウンロード)
CPU: AVX2対応の最新のx86-64プロセッサ (Intel Haswell 2013以降 / AMD Excavator 2015以降)
GPU: 不要 — すべての推論はONNX Runtime経由でCPU上で実行されます

トラブルシューティング

Claude Codeを再起動してください（フックは起動時に読み込まれます）
HTTPサーバーを確認してください: curl http://127.0.0.1:27182/api/health

~/.claude.json に正しいPythonパスで roampal-core MCPエントリがあるか確認してください
Claude Codeの出力パネルでMCPエラーを確認してください

roampal init --opencode を実行したか確認してください
サーバーが自動起動しているか確認してください: curl http://127.0.0.1:27182/api/health
起動していない場合は手動で開始してください: roampal start

これは想定内の動作です。Roampalには自己修復機能があり、HTTPサーバーが応答しなくなると自動的に再起動して再試行されます。

まだ解決しませんか？ AIに助けを求めてください。ログを読み取り、Roampalの問題を直接デバッグできます。

サポート

Roampal Coreは完全に無料のオープンソースです。

開発支援: roampal.gumroad.com
機能のアイデアやフィードバック: Discord
バグ報告: GitHub Issues
AIメモリに関するヘルプが必要な場合: roampal@protonmail.com | LinkedIn

ライセンス

Apache 2.0

roampal-core