Contextforge

ContextForge MCP — Claude、Cursor、Copilot の永続メモリー

Model Context Protocol（MCP）を通じて、Claude Code、Cursor、GitHub Copilot にセッションをまたいで保持される永続メモリーを提供します。プロジェクトについて毎回説明し直す必要はありません。

ContextForge MCP は、AI コーディングアシスタントを長期にわたって検索可能なメモリーに接続するオープンソースの MCP サーバーです。意思決定、アーキテクチャに関するメモ、デバッグのコンテキスト、プロジェクトの知識を、MCP をサポートするあらゆるツールのセッションで利用できます。

• 🧠 永続メモリー — AI がセッション、日数、週数をまたいであらゆることを記憶します
• 🔍 セマンティック検索 — キーワードではなく、意味から知識を検索できます
• 🔗 1つのメモリーをあらゆるツールで — Claude Code、Cursor、Copilot、Claude Desktop、Windsurf
• 🐙 Git 連携 — コミットと PR を自動的に同期します
• ✅ タスク追跡 — イシュー、担当者、プロジェクトのステータスを管理できます
• 👥 チームコラボレーション — プロジェクトとメモリーをチームで共有できます
• 🆓 無料プラン — クレジットカードなしで始められます

メモ

設定不要で自動的に動作します（v0.5.1 以降）。 接続時、サーバーは AI クライアントに起動時の指示を送信します。指示に従うクライアント（Claude Desktop、Claude Code）は、毎回のセッション開始時にプロジェクトのメモリーを読み込み、新しい意思決定を先回りして保存します。設定を編集する必要はありません。init（ステップ 4）の実行は必須ではなくなり、補強として機能します。また、サーバーの指示にまだ従わないクライアント（例：Cursor）でも引き続き役立ちます。

---

クイックスタート

1. インストール

インストール手順は不要です。以下のセットアップでは npx -y contextforge-mcp を使ってサーバーを実行します。必要に応じて取得し、最新の状態に保ちます。

コールドスタートを少し速くするため、グローバルにインストールしたい場合は npm install -g contextforge-mcp を任意で実行できます。実行した場合は、以下のコマンドから npx -y を省略できます。

2. API キーを取得

1. contextforge.dev にアクセスします
2. サインアップします（無料プランを利用できます）
3. Settings → API Keys → Generate API Key の順に選択します
4. キーをコピーします（cf_ で始まります）

3. AI ツールに接続

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json を編集します。

{
  "mcpServers": {
    "contextforge": {
      "command": "npx",
      "args": ["-y", "contextforge-mcp"],
      "env": {
        "CONTEXTFORGE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Desktop を再起動します。

Claude Code（CLI）

claude mcp add contextforge -s user \
  -e CONTEXTFORGE_API_KEY=your-api-key-here \
  -- npx -y contextforge-mcp

Claude Code を再起動し、/mcp を実行して接続を確認します。

Cursor

Cursor の MCP 設定に追加します。

{
  "mcpServers": {
    "contextforge": {
      "command": "npx",
      "args": ["-y", "contextforge-mcp"],
      "env": {
        "CONTEXTFORGE_API_KEY": "your-api-key-here"
      }
    }
  }
}

GitHub Copilot（VS Code）

Copilot の MCP 設定に追加します。

{
  "servers": {
    "contextforge": {
      "command": "npx",
      "args": ["-y", "contextforge-mcp"],
      "env": {
        "CONTEXTFORGE_API_KEY": "your-api-key-here"
      }
    }
  }
}

4. プロジェクトを初期化する（推奨）

v0.5.1 以降では、対応クライアントでサーバーがメモリを自動的に読み込むため（冒頭の注記を参照）、この手順は省略できますが、推奨されます。動作を補強し、サーバーの指示に従わないクライアントにも対応するとともに、組み込みのファイルベースのメモリを完全に上書きできます。

AI エディターが常に ContextForge のメモリを優先するようにプロジェクトを設定します。

npx contextforge-mcp init

デフォルトでは、init がプロジェクトで使用しているエディターを自動検出し、3 つのルールセクションと 2 つのフックを書き込みます。

• メモリルール — メモリに関する質問を、組み込みのファイルベースのメモリではなく ContextForge に振り分けます
• セッションプレゼンスルール — 並行セッションが会話の開始時と大きな変更を行う前に、互いの存在を確認するようにします
• 起動時コンテキストルール — すべての会話の開始時に、ContextForge からプロジェクトの短い概要（概要、未完了のタスク、進行中のセッション）を読み込みます
• 圧縮後の想起フック（Claude Code のみ）— .claude/settings.json に compact をマッチャーとする SessionStart フックを設定します。Claude Code が長い会話を圧縮すると、このフックが npx -y contextforge-mcp recall を実行し、セッションの目的、作業中の内容に関連するメモリ、プロジェクトの最新のメモリ 10 件、保留中のタスクを再注入します。これにより、ContextForge に保存した判断が要約後も保持されます。
• セッション目的フック（Claude Code のみ、0.13.0）— 生成されたスクリプト .claude/hooks/contextforge-objective.cjs を node で直接実行する（約 50 ミリ秒）UserPromptSubmit フックです。プロンプトを使用中のマシンにある ~/.contextforge-mcp/sessions/<session_id>.jsonl に記録するため、圧縮後に recall がセッションの目的を復元できます。ログは 14 日後に整理され、アップロードされることはありません。recall が送信する内容については、以下のプライバシーに関する注記を参照してください。

書き込まれるファイル：

• Claude Code 用の CLAUDE.md（検出条件：既存の CLAUDE.md または .claude/ ディレクトリ）
• Cursor 用の .cursorrules（検出条件：既存の .cursorrules または .cursor/ ディレクトリ）
• Claude Code 用の .claude/settings.json — 統合され、上書きされることはありません。追加されるのは 2 つの ContextForge フックグループのみです
• Claude Code 用の .claude/hooks/contextforge-objective.cjs — 生成される目的フックスクリプトです（コミットしても安全です。新しいバージョンがリリースされると init によって更新されます。XML 風のタグで始まり、閉じタグを含む Claude Code 独自のシステムターン（プロンプト）は記録されません）

エディターが検出されない場合は、両方のファイルが生成されます。

サーバーの指示に従うクライアント（Claude Desktop、Claude Code）では、この手順を行わなくても ContextForge が自動的に使用されます。その他のクライアントでは、または組み込みのファイルベースの自動メモリが優先されないようにするには、init を実行してください。メモリを常に ContextForge に振り分ける明示的なルールが書き込まれます。

--editor で上書きする

フラグ	動作
--editor=claude	CLAUDE.md のみ生成します
--editor=cursor	.cursorrules のみ生成します
--editor=all	検出をスキップし、両方を生成します

init を再実行しても、セクションごとに冪等です。すでに存在するセクションはそのまま残り、不足しているセクションだけが追加されます。古いバージョンからアップグレードする場合は、npx contextforge-mcp init を再実行するだけです。ファイルの他の部分には触れず、新しい起動時コンテキストセクションが追加されます。

バージョンを確認する

npx contextforge-mcp --version   # also: -v, version

インストールされているバージョンを出力します（例：contextforge-mcp 0.5.2）。

コンパクション後の情報保持（Claude Code）

長いセッションはコンパクションされます。Claude Code は会話を要約して空き容量を確保しますが、要約には要点が残る一方で詳細は失われます。通常は決定事項が、多くの場合はタスクそのものが失われます。init は、これら両方を解決する2つのフックをインストールします。

1. 目的フック（UserPromptSubmit） — 各プロンプトをローカルに記録するため、セッションで最初に送信した実際のリクエストが要約によって失われることはありません。
2. 想起フック（SessionStart、マッチャー compact） — コンパクションのたびに直後に実行され、次の情報をこの順序で表示します。セッションの目的とコンパクション直前の最新リクエスト、現在の作業に関連する最大5件のメモ（目的、git ブランチ、最近のコミットの件名、変更ファイルを使ったセマンティック検索。メモの古さは問いません）、プロジェクトの最新メモ10件、保留中のタスク最大5件、さらに古い情報には memory_query を呼び出すよう促すリマインダーです。ブロック全体は約4 KB に収まり、一度だけ挿入され、固定されないため、コンパクショントリガーの位置には影響しません。

関連性検索は、コンパクションごとに1回、使用量が計上されるクエリを実行します。セッションの目的がある場合、またはデフォルト以外のブランチを使用している場合にのみ実行されます（main での git のみのコンテキストはノイズです）。他の取得処理と並行して、同じ6秒のステージ期限内に実行されるため、検索が遅くてもブロックの残りが失われることはありません。また、環境変数に CONTEXTFORGE_RECALL_RELEVANCE=0 を設定すると、完全に無効になります。

フックは通常のシェルコマンドとして実行されるため、recall は API キーを、設定されていれば CONTEXTFORGE_API_KEY から、そうでなければ ~/.claude.json の contextforge サーバーエントリ（claude mcp add が保存する場所）から、それ以外の場合はプロジェクトの .mcp.json から読み取ります。リンク済みのプロジェクト（リポジトリのルートに .contextforge があること）が必要です。必要なものが不足している場合は何も出力せず、セッションを妨げることもありません。シェルプロファイルで設定した CONTEXTFORGE_API_KEY は ~/.claude.json より優先されるため、古いキーが設定されていると recall は何も表示しない点に注意してください。

プロジェクトディレクトリから手動で試すには、次を実行します。

npx contextforge-mcp recall           # prints the block for the newest session in this directory
npx contextforge-mcp recall --stats   # local numbers: recalls, objective coverage, follow-up queries

プライバシー：プロンプトログと想起の統計情報は、お使いのマシン上の ~/.contextforge-mcp/ に保存され、アップロードされることはありません。マシン外に送信される情報：コンパクション後、recall はセッションの目的（最大600文字。git ブランチ、最近のコミットの件名、変更ファイル名とともに）を検索クエリとして ContextForge に送信します。これは memory_query がクエリを送信するのと同じ方法であり、保存されることはありません。.claude/settings.json は通常コミットされるため、リポジトリをプルしたチームメンバーにもプロンプトフックが適用されます。オプトアウトするには、UserPromptSubmit グループを削除してください。

すでに ContextForge を使用していますか？（既存ユーザー向け）

再設定は不要です。最新版に更新して、AI クライアントを再起動してください。

npm update -g contextforge-mcp   # only if you installed globally; npx users get it on next launch

自動読み込みの動作には、init を再実行する必要はありません。コンパクション後の想起フックとセッションの目的フックを使用するには、各プロジェクトで一度 npx contextforge-mcp init を実行してください。不足している設定だけが追加されます。0.13.2以降では、想起フックはインストール済みでも目的フックがない、または古い場合、サーバーがプロジェクトごとに一度だけ通知します。

---

利用可能なツール

ContextForge は、ナレッジ管理、GitHub 連携、課題追跡、コラボレーションにわたる 69 個のツールを定義しています。機能が削除されたことは一度もなく、以下のすべてのツールを完全に呼び出せます。ただし v0.11.0 以降、AI クライアントにデフォルトで表示されるのは 11 個のみです（デフォルトの CONTEXTFORGE_TOOLS=lean）。

• コアツール 10 個 — 毎回のセッションでエージェントが自律的に使用するツールです：memory_query、memory_ingest、memory_check_freshness、memory_confirm、memory_correct、memory_forget、tasks_list、tasks_what_next、session_list、memory_help。
• cf_tools — 残り 59 個のツールを検出して実行するゲートウェイツールです。AI に自然な言葉で依頼すると（「git のコミットを同期して」「スナップショットから復元して」「olvida ese recuerdo viejo」など）、ツールを検索（英語またはスペイン語）し、適切なツールを呼び出します。正確な名前を知っている必要はありません。

代わりに、CONTEXTFORGE_TOOLS=full を設定すると、69 個すべてのツールがクライアントに直接表示され、0.11.0 より前のバージョンと同じ動作になります。環境変数を参照してください。

デフォルトで lean が選ばれている理由：69 個のツールスキーマは、セッションごとに約 15,000 トークンのコンテキストを消費し、Cursor の 40 ツール上限を超え、さらに、複数のクライアントで約 50 個を超えると見られる精度低下の一因になります。lean セットでは、cf_tools 経由ですべてのツールを 1 回の呼び出しで利用できる状態を保ちながら、これを約 3,500 トークン（約 77％削減）まで抑えられます。

ナレッジ管理

ツール	説明
memory_ingest	ナレッジをメモリに保存
memory_query	ナレッジを意味的に検索
memory_list_items	保存済みの項目をすべて一覧表示
memory_delete	特定の項目を削除
memory_ingest_batch	複数の項目を一度に保存
memory_delete_batch	フィルターで項目を削除

スペースとプロジェクト

ツール	説明
memory_list_spaces	スペースを一覧表示
memory_create_space	新しいスペースを作成
memory_delete_space	スペースを削除
memory_move_space	スペースをプロジェクトに移動
memory_list_projects	プロジェクトを一覧表示
memory_create_project	新しいプロジェクトを作成
memory_delete_project	プロジェクトを削除
memory_link_project	ディレクトリをプロジェクトにリンク
memory_unlink_project	ディレクトリのリンクを解除
memory_current_project	リンク済みのプロジェクトを表示

GitHub 連携

ツール	説明
memory_git_connect	GitHub リポジトリを接続
memory_git_list	接続済みのリポジトリを一覧表示
memory_git_activate	Webhook を有効化／無効化
memory_git_sync	既存の履歴をインポート
memory_git_commits	同期済みのコミットを一覧表示
memory_git_prs	同期済みの PR を一覧表示
memory_git_disconnect	リポジトリの接続を解除

課題追跡

ツール	説明
issues_list	課題を一覧表示
issues_create	新しい課題を作成
issues_start	対応中としてマーク
issues_resolve	解決済みとしてマーク
issues_resolve_by_name	タイトルで解決
issues_assign	コラボレーターに割り当て
issues_what_next	推奨事項を取得

コラボレーション

ツール	説明
project_share	メールでプロジェクトを共有
collaborators_list	コラボレーターを一覧表示

スナップショットとエクスポート

ツール	説明
memory_snapshot_create	バックアップを作成
memory_snapshot_list	スナップショットをすべて一覧表示
memory_snapshot_restore	バックアップから復元
memory_snapshot_delete	スナップショットを削除
memory_export	JSON/MD/CSV にエクスポート
memory_import	ファイルからインポート

ユーティリティ

ツール	説明
memory_stats	使用状況の統計を表示
memory_relate	2 つの項目をリンク
memory_help	ヘルプを表示

---

セッションプレゼンス（複数セッションの連携）

複数の Claude Code セッションを並行して実行していますか（worktree、エージェントチームなど）？ 各 MCP プロセスは実行中、自動的にライブセッションとして登録され、ハートビートを送信します。 正常に終了すると、セッションはただちに削除されます（ホストプロセスが強制終了されている間も、分離されたヘルパーが終了通知を送信します）。プロセスが異常終了した場合は、最後のハートビートから約10分後にセッションの有効期限が切れます。 エージェントが連携するためのツールが3つあります。session_list はコアツールで、常に表示されます。session_update と session_end は、デフォルトでは cf_tools ゲートウェイ経由で使用します（または CONTEXTFORGE_TOOLS=full を設定すると、3つすべてを直接表示できます）。

ツール	機能
session_update	このセッションで取り組んでいる内容を宣言します（「認証モジュールに取り組んでいます」など）
session_list	共有領域に手を加える前に、同じプロジェクト内のほかのライブセッションとその作業内容を確認します（組織全体を確認するには all_projects: true を渡します）
session_end	このセッションのプレゼンスを明示的に終了します（終了時に自動でも実行されます）

デフォルトでは、session_list の対象は現在のプロジェクトに限定されます。実際に作業が競合するのはこの範囲です。複数のプロジェクトがある組織で、すべてのセッションを確認するには all_projects: true を渡し、別の範囲に限定するには project: "<name-or-id>" を指定します。

CLAUDE.md では、会話の開始時に session_list を呼び出し、タスクの開始時または切り替え時に session_update を呼び出すパターンをおすすめします。

---

自然言語での例

コマンドを覚える必要はありません。AI に自然に話しかけるだけです。

# Knowledge
"Save this: we use PostgreSQL for the main database"
"What database do we use?"
"List my spaces"

# GitHub
"Connect my repo github.com/myuser/myproject"
"What commits did I make today?"
"Show PRs merged this week"

# Issues
"Create an issue: Update the login page design"
"What's pending?"
"What should I work on next?"
"Mark the login issue as done"

---

環境変数

変数	必須	説明
CONTEXTFORGE_API_KEY	はい	ダッシュボードで取得した API キー
CONTEXTFORGE_API_URL	いいえ	API エンドポイント（デフォルトは本番環境）
CONTEXTFORGE_DEFAULT_SPACE	いいえ	操作に使用するデフォルトのスペース
CONTEXTFORGE_TOOLS	いいえ	lean（デフォルト）では11個のツールを公開します。最もよく使われる10個と、残り59個のツールを利用するための cf_tools ゲートウェイです。full では69個すべてを公開します（0.11.0より前のバージョンと同じです）。Lean により、Cursor の40個のツール上限と、Claude Code の50個のツールによる性能低下のしきい値を超えずに ContextForge を利用できます。

---

仕組み

ContextForge MCP は、Model Context Protocol のツール呼び出しを、認証済みの HTTP リクエストに変換して ContextForge API に送信する軽量クライアントです。ナレッジはサーバー側で保存、インデックス化（セマンティック埋め込み）、取得されるため、MCP クライアント自体はステートレスです。

つまり、次のようなメリットがあります。

• インフラの管理が不要 — ローカルデータベースも、埋め込みの実行も、ベクトルストアの保守も必要ありません
• AI が使える場所ならどこでも動作 — Claude Code、Cursor、Copilot などで同じメモリを利用できます
• チームでの共同作業 — 共有プロジェクトはリアルタイムで同期されます

---

ダッシュボード

contextforge.dev で、メモリを視覚的に管理できます。

• ナレッジを表示して整理する
• メモリを検索して絞り込む
• API キーと請求を管理する
• 問題を追跡して共同作業する
• データをエクスポートしてバックアップする

---

開発

# Clone and install
git clone https://github.com/alfredoizdev/contextforge-mcp.git
cd contextforge-mcp
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode
npm run dev

---

コントリビューション

github.com/alfredoizdev/contextforge-mcp で、課題の報告やプルリクエストを歓迎しています。

---

サポート

• 📖 ドキュメント
• 🐛 問題を報告
• 💬 ご質問：[email protected]

---

ライセンス

MIT © Alfredo Izquierdo