RemembrallMCP

RemembrallMCP

AI コーディングエージェントのための、コードベース全体のナレッジです。Rust、Postgres + pgvector で構築されたフィールドを認識するコードグラフと永続メモリを、MCP 経由で提供します。

問題： AI コーディングエージェントは、セッションごとに本の数ページしか見ることができません。grep して読み、コードベースがどう連携しているかを一から導き出します。何が何を呼び出すのかを示すマップも、何かを変更したときに何が壊れるかを知る方法も、過去のセッションで決定した内容を記憶する仕組みもありません。

解決策： RemembrallMCP は、9 言語にわたるフィールドを認識する依存関係グラフ（関数、クラス、メソッド、フィールドと、それらの間の参照）と、セッション間で保持される永続メモリによって、コードベース全体をエージェントに提供します。

1. フィールドを認識するコードグラフ - tree-sitter で構築する、コードベースの最新マップです。9 言語にわたる関数、クラス、メソッド、データフィールドに加え、呼び出し、インポート、定義、継承、フィールド参照の関係を扱います。「これを変更すると何が壊れるか」を、単一の構造体フィールドに至るまで質問でき、エージェントが何かに手を加える前にミリ秒単位で回答を得られます。

2. 永続メモリ - セッション間で保持される決定事項、パターン、組織のナレッジです。セマンティック検索と全文検索を組み合わせたハイブリッド検索により、関連するコンテキストをすぐに見つけられます。

remembrall_recall("authentication middleware patterns")
-> 3 relevant memories from past sessions

remembrall_index("/path/to/project", "myapp")
-> Builds dependency graph: 847 symbols, 1,203 relationships

remembrall_impact("AuthMiddleware", direction="upstream")
-> 12 files depend on AuthMiddleware (with confidence scores)

remembrall_impact("amount", direction="upstream")
-> methods that read self.amount, across the whole codebase

remembrall_store("Switched from JWT to session tokens because...")
-> Decision stored for future sessions

コードグラフが重要な理由

RemembrallMCP がなければ、エージェントはセッションのたびにコードベースを一から調べます。Claude Code は Explore エージェントを起動し、Codex は何十ものファイルを読み、Cursor はディレクトリを grep します。どれも、何が何を呼び出すのかを理解するだけでトークンと時間を消費します。「この関数を呼び出すすべての箇所を見つける」という単純なタスクでも、複数のツール呼び出しにわたって数千トークンを消費することがあります。

RemembrallMCP があれば、同じクエリは単一の remembrall_impact 呼び出しで済み、探索トークンを消費せずに <1ms で結果が返ります。依存関係グラフはすでに構築され、利用できる状態です。

	RemembrallMCP なし	RemembrallMCP あり
「UserService を呼び出しているのは何ですか？」	エージェントが grep し、8～15 個のファイルを読み、サブエージェントを起動	remembrall_impact - 1 回の呼び出し、<1ms
「認証ミドルウェアはどこで定義されていますか？」	エージェントが glob し、一致した箇所を読み、絞り込む	remembrall_lookup_symbol - 1 回の呼び出し、<1ms
「amount フィールドを参照しているのはどこですか？」	エージェントが self.amount を grep し、ORM やモジュールをまたぐ使用箇所を見落とす	remembrall_impact - 1 回の呼び出し、<1ms
「キャッシュについて何を決めましたか？」	エージェントにはコンテキストがなく、ユーザーに尋ねる	remembrall_recall - 1 回の呼び出し、約 25ms
一般的な探索コスト	質問ごとに 5,000～20,000 トークン	約 200 トークン（ツール呼び出し + 応答）

コードベースが大きいほど、節約効果は高まります。小規模なプロジェクトなら、エージェントは grep と読み込みで一通り調べられます。しかし、500 ファイルのモノレポでは、その探索がボトルネックになります。エージェントはコンテキスト制限に達したり、複数のサブエージェントを起動したり、モジュールをまたぐ依存関係を完全に見落としたりします。RemembrallMCP のグラフクエリは、プロジェクトの規模にかかわらず 10ms 未満で完了します。構造が実行時に発見されるのではなく、Postgres に事前インデックス化されているためです。

これが、毎回本の数ページを読むエージェントと、コードベース全体をすでに把握しているエージェントの違いです。

ベンチマーク

RemembrallMCP は現在、次の 2 つの領域でベンチマークを実施しています。

• コードタスクにおけるエージェントの生産性 - pallets/click v8.1.7（594 個のシンボル、1,589 個の関係）でテストしています。RemembrallMCP ありとなしで、同一のコーディングタスクを 5 回実行します。完全なレポート。
• メモリの想起品質 - 検索品質、フィルタリング、エッジケース、ランキング、レイテンシを網羅する 31 件の正解データ付きクエリを対象に、ローカルの想起ハーネスを実行しています。

指標	RemembrallMCP なし	RemembrallMCP あり	差分
ツール呼び出し総数（5 タスク）	112	5	-95.5%
推定トークン数	~56,000	~1,000	-98.2%
質問あたりの平均ツール呼び出し数	22.4	1.0	-95.5%

大規模なコードベースほど、削減効果は大きくなります。Click は約 90 ファイルです。500 ファイルを超えるモノレポでは、RemembrallMCP を使用しないエージェントは規模に応じて探索の呼び出しが増える一方、グラフクエリはサイズにかかわらず 10ms 未満に収まります。

メモリ想起の指標	結果
合格したクエリ数	31 / 31
Recall@5	0.917
Precision@5	0.619
MRR	0.908
p95 レイテンシ	14ms

ベンチマークを自分で実行するには、ハーネスとタスク定義がある benchmarks/ を参照してください。

メモリ検索、長期記憶、コードグラフの正確性、エージェントの生産性を対象とする、より広範なベンチマーク戦略については、docs/benchmark-roadmap.md を参照してください。

要件

• Docker（最も簡単なセットアップの場合）、または pgvector を使用する PostgreSQL 16
• GitHub から取り込む場合：GitHub CLI（gh）をインストールし、認証済みであること

クイックスタート

オプション 1：Docker Compose（最も簡単）

git clone https://github.com/roboticforce/remembrallmcp.git
cd remembrallmcp

# Start Postgres, initialize the schema, download the embedding model,
# and run the MCP server. The remembrall container stays up after setup.
docker compose up -d

# Verify it's running (database connected, schema ready)
docker compose exec remembrall remembrall status

これだけです。pgvector を備えた Postgres、スキーマ、埋め込みモデルがすべて自動的にセットアップされます。データベースとモデルキャッシュは再起動後も保持されます。

remembrall コンテナは起動時に remembrall init（べき等なセットアップ）を実行し、その後 remembrall serve を実行するため、起動したままになり、docker compose exec で status、doctor、その他のコマンドを実行できます。

MCP クライアント（Claude Code、Cursor、Codex）をサーバーに接続する方法については、以下のお使いの MCP クライアントへの接続を参照してください。

オプション 2：ビルド済みバイナリをダウンロード

# macOS (Apple Silicon)
curl -fsSL https://github.com/roboticforce/remembrallmcp/releases/latest/download/remembrall-aarch64-apple-darwin.tar.gz | tar xz
sudo mv remembrall /usr/local/bin/

# Linux (x86_64)
curl -fsSL https://github.com/roboticforce/remembrallmcp/releases/latest/download/remembrall-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv remembrall /usr/local/bin/

# Initialize (sets up Postgres via Docker, creates schema, downloads model)
remembrall init

オプション 3：ソースからビルド（Rust 1.94 以降が必要）

cargo build -p remembrall-server --release
# Binary is at target/release/remembrall

remembrall init

お使いの MCP クライアントへの接続

Codex

Codex は同じ MCP サーバー定義形式を使用します。サーバーを remembrall として登録し、インストール済みのバイナリまたはローカルのリリースビルドを指定してください。

remembrall が PATH にインストールされている場合：

{
  "mcpServers": {
    "remembrall": {
      "command": "remembrall"
    }
  }
}

ローカルのソースチェックアウトから実行する場合：

{
  "mcpServers": {
    "remembrall": {
      "command": "/path/to/remembrallmcp/target/release/remembrall",
      "env": {
        "DATABASE_URL": "postgres://postgres:postgres@localhost:5450/remembrall"
      }
    }
  }
}

Codex から Docker Compose を使用する場合：

{
  "mcpServers": {
    "remembrall": {
      "command": "docker",
      "args": ["compose", "-f", "/path/to/remembrallmcp/docker-compose.yml", "run", "--rm", "-T", "remembrall"]
    }
  }
}

サーバーを追加した後、Codex を再起動して再接続し、ツールを読み込ませてください。

Claude Code、Cursor、その他の MCP クライアント

プロジェクトの .mcp.json に追加してください（Claude Code、Cursor、および MCP 互換のすべてのクライアントで動作します）。

ビルド済みバイナリを使用する場合、またはソースからビルドした場合：

{
  "mcpServers": {
    "remembrall": {
      "command": "remembrall"
    }
  }
}

Docker Compose を使用する場合：

{
  "mcpServers": {
    "remembrall": {
      "command": "docker",
      "args": ["compose", "-f", "/path/to/remembrallmcp/docker-compose.yml", "run", "--rm", "-T", "remembrall"]
    }
  }
}

呼び出しごとに新しいコンテナを起動し、remembrall init（べき等。出力は stderr に送られるため、MCP ストリームを破損することはありません）を実行した後、stdio 経由で remembrall serve を実行します。JSON-RPC を正常に通過させるには、TTY の割り当てを無効にする -T フラグが必要です。depends_on により、db サービスが自動的に起動します。

ソースから実行する場合（PATH にインストールされていない場合）：

{
  "mcpServers": {
    "remembrall": {
      "command": "/path/to/remembrallmcp/target/release/remembrall",
      "env": {
        "DATABASE_URL": "postgres://postgres:postgres@localhost:5450/remembrall"
      }
    }
  }
}

MCP クライアントを再起動してください。9 個のツールがすべて自動的に利用可能になります。

試してみる

> "Store a memory: We chose Postgres over MongoDB because our query patterns
   are relational. Type: decision, tags: database, architecture"

> "Recall what we know about database decisions"

> "Index this project and show me the impact of changing UserService"

MCP ツール

メモリ

ツール	説明
remembrall_recall	メモリを検索します。セマンティック検索と全文検索をRRFで融合します
remembrall_store	ベクトル埋め込みを使って、決定事項、パターン、ナレッジを保存します
remembrall_update	既存のメモリ（内容、要約、タグ、重要度）を更新します
remembrall_delete	UUIDでメモリを削除します
remembrall_ingest_github	GitHubリポジトリからマージ済みPRの説明を一括インポートします
remembrall_ingest_docs	ディレクトリをスキャンしてMarkdownファイルを探し、メモリとして取り込みます

コードインテリジェンス

ツール	説明
remembrall_index	プロジェクトディレクトリを解析し、フィールドを認識するコードグラフを構築します（9言語の関数、クラス、メソッド、フィールド）
remembrall_impact	影響範囲を分析します。「これを変更すると何が壊れるか？」を調べます。関数、クラス、メソッド、フィールドに対応しています
remembrall_lookup_symbol	プロジェクト全体から、関数、クラス、メソッド、フィールドの定義箇所を検索します

対応言語

言語	拡張子	品質スコア
Python	.py	A (94.1)
Java	.java	A (92.6)
JavaScript	.js, .jsx	A (92.0)
Rust	.rs	A (91.0)
Go	.go	A (90.7)
Ruby	.rb	B (87.9)
TypeScript	.ts, .tsx	B (84.3)
Kotlin	.kt, .kts	B (82.9)
C#	.cs	A (96.8)

スコアは、実際のオープンソースプロジェクト（Click、Gson、Axios、bat、Cobra、Sidekiq、Hono、Exposed、MediatR）を対象に、自動グラウンドトゥルーステストを使って測定しています。C#のスコアはMediatR 12.4.1（シンボル69個、関係48個、影響クエリ9件、エッジケース10件）を対象に測定しています。シンボル、インポート、エッジケースの精度は100％で、差分はジェネリックインターフェースの継承（: IPipelineBehavior<TRequest, TResponse>がクラスシンボルではなく合成UUIDに解決される）と、フィールドディスパッチ呼び出しの誤解決によるものです。C#のフィールドレベル参照は、フィールドキャプチャ用フィクスチャで個別に検証されており、精度は100％です。

初期セットアップ

新しいRemembrallMCPインスタンスにはナレッジがありません。既存のプロジェクト履歴から初期データを取り込むには、取り込みツールを使用してください。

GitHubのPR履歴から取り込む場合：

> remembrall_ingest_github repo="myorg/myrepo" limit=100

gh経由でマージ済みPRを取得し、タイトルと本文をメモリに整理して、プロジェクトごとにタグ付けします。本文が50文字未満のPRはスキップされます。コンテンツフィンガープリントによる重複排除により、再実行時の再取り込みを防ぎます。

Markdownドキュメントから取り込む場合：

> remembrall_ingest_docs path="/path/to/project"

ディレクトリツリーを走査し、すべての.mdファイルを探して、H2見出しごとに分割し、各セクションを検索可能なメモリとして保存します。node_modules、.git、targetなどのディレクトリはスキップします。README、ARCHITECTURE、ADR、およびあらゆる文書の取り込みに適しています。

プロジェクトごとに両方を一度ずつ実行してください。取り込み後、remembrall_recallですぐにコンテキストを利用できます。

アーキテクチャ

Source Code                   Organizational Knowledge
    |                                 |
    v                                 v
Tree-sitter Parsers           Ingestion Pipeline
(9 languages)                 (GitHub PRs, Markdown docs)
    |                                 |
    v                                 v
+--------------------------------------------------+
|              Postgres + pgvector                  |
|                                                   |
|  memories (text + embeddings + metadata)          |
|  symbols (functions, classes, methods, fields)    |
|  relationships (calls, imports, defines,          |
|                 inherits, references)             |
+--------------------------------------------------+
                          |
                    MCP Server (stdio)
                          |
              Any MCP-compatible AI agent

• 解析： tree-sitter（Rustバインディングを使用し、パイプラインにPythonは含まれません）
• 埋め込み： fastembed（all-MiniLM-L6-v2、384次元、インプロセスのONNX Runtime）
• 検索： ハイブリッドRRF（セマンティックコサイン類似度＋全文tsvector）
• グラフクエリ： 循環検出と信頼度減衰を備えた再帰的CTE
• トランスポート： rmcp経由のstdio

CLIコマンド

コマンド	説明
remembrall init	データベース、スキーマ、埋め込みモデルをセットアップします
remembrall serve	MCPサーバーを実行します（サブコマンドを指定しない場合のデフォルト）
remembrall start	Dockerデータベースコンテナを起動します
remembrall stop	Dockerデータベースコンテナを停止します
remembrall status	メモリ数、シンボル数、接続状態を表示します
remembrall doctor	よくある問題（Docker、pgvector、スキーマ、モデル）を確認します
remembrall reset --force	スキーマを削除して再作成します（すべてのデータを削除します）
remembrall version	バージョンと設定パスを表示します

設定

設定ファイル：~/.remembrall/config.toml（remembrall init によって作成されます）

環境変数は設定ファイルの値を上書きします。

変数	説明
REMEMBRALL_DATABASE_URL または DATABASE_URL	PostgreSQL の接続文字列
REMEMBRALL_SCHEMA	データベースのスキーマ名（デフォルト：remembrall）

プロジェクト構成

crates/
  remembrall-core/          # Library - parsers, memory store, graph store, embedder
  remembrall-server/        # MCP server + CLI binary
  remembrall-test-harness/  # Parser quality testing against ground truth
  remembrall-recall-test/   # Search quality testing
docs/                       # Architecture and test plan docs
test-fixtures/              # Ground truth TOML files for 9 languages
tests/                      # Recall test fixtures

パフォーマンス

操作	時間
メモリの保存	7ms
セマンティック検索（HNSW）	<1ms
全文検索	<1ms
ハイブリッド想起（エンドツーエンド）	~25ms
影響分析	4-9ms
シンボル検索	<1ms
Python ファイル 89 件のインデックス作成	2.3s

ライセンス

MIT