Threadctx

threadctx-mcp

AI コーディングエージェント向けの共有メモリ MCP サーバーです。Claude Code、Cursor、あらゆる MCP クライアントで同じように動作します。同じパッケージ、同じ形式の設定を使うため、クライアントごとの統合作業は不要です。初回起動時には、リポジトリで使用しているエージェントのルールファイル（AGENTS.md、CLAUDE.md、Copilot、Windsurf、Cline、Gemini）に「チームのメモリを確認する」という指示も追加されるため、メモリが公開されるだけでなく、実際に読み込まれます。

このリポジトリ自体がこのツールを使っています。AGENTS.md と CLAUDE.md は、実行するコマンドと同じ npx threadctx-mcp init で設定しました。実際の様子を確認したい場合は、Git の履歴をご覧ください。

モード

• ローカル（デフォルト、無料、登録不要）： メモリは ~/.threadctx/local.json にプレーンな JSON ファイルとして保存されます。ネイティブ依存関係は一切ないため、Node 18 以降を搭載したあらゆるマシンに npx threadctx-mcp をすぐにインストールできます（コンパイラーや node-gyp の手順は不要です）。ネットワークへのアクセスは、エージェントがすでに使用している LLM プロバイダーへのものに限られます。キーワードベースで、現在のリポジトリ（git remote から検出）を対象に検索します。npx threadctx-mcp list を実行すれば、エージェントが保存した内容をいつでも正確に確認できます。
• クラウド（有料の Team ティア以上）： リポジトリのメンバー全員でメモリを共有でき、実際のセマンティック検索を利用できます。threadctx.dev の API キーが必要です（または、独自のセルフホスト環境を使用してください。詳しくは ../cloud/README.md をご覧ください）。

クイックスタート

# Local mode — nothing to configure. Also auto-adds the "check team memory"
# instruction to your agents' rule files (AGENTS.md, CLAUDE.md, and any
# detected tool-specific files) on first start.
npx threadctx-mcp

# Set a repo up for your whole team (run once, commit the results)
npx threadctx-mcp init

# Cloud mode — shared team memory via threadctx.dev
npx threadctx-mcp init --mode=cloud --api-key=tctx_xxx

# Joining a repo a teammate already set up? One command:
npx threadctx-mcp join

# See what your agents have written to this machine
npx threadctx-mcp list            # this repo
npx threadctx-mcp list --all      # every repo

init は、コミット可能でシークレットを含まない3つのファイルを書き込みます。.threadctx.json（{ "mode": ... } のみ）、.mcp.json（Claude Code のプロジェクト設定）、.cursor/mcp.json（Cursor のプロジェクト設定）です。3つすべてをコミットしてください。これにより、リポジトリを Claude Code または Cursor で開いたチームメンバーには、何もインストールや設定をしなくても、threadctx を有効にするよう自動的にプロンプトが表示されます。それ以外の MCP クライアントを使うチームメンバーは、npx threadctx-mcp join を実行すると、同じ方法でマシンがセットアップされ、使用するクライアント用の設定ブロックが出力されます。

API キーはコミット対象のファイルに一切記載されません。実行時に THREADCTX_API_KEY 環境変数から読み込まれるため（シェルプロファイルでエクスポートしてください）、シークレットがバージョン管理に含まれることはありません。

threadctx は、タスクの前にエージェントが memory_query を呼び出し、後に memory_write を呼び出すよう、プロジェクトのルールに明確に識別できる短い指示も追加します。毎回、どのツールでも使える2つのファイル（Copilot、Cursor、Windsurf、Zed、Codex、Aider など約24のツールが読み込む共通規格の AGENTS.md と、Claude Code のより高機能なネイティブ形式である CLAUDE.md）に加え、.cursor/rules/threadctx.mdc を書き込みます。その後、リポジトリ内で使用が確認されたツールに限って、ツール固有のファイルを追加します。そのため、使っていないツールのルールファイルがプロジェクトに散らばることはありません。

ツール	書き込まれるファイル	書き込み条件
ツール共通規格	AGENTS.md	常に
Claude Code	CLAUDE.md	常に
Cursor	.cursor/rules/threadctx.mdc	常に
GitHub Copilot	.github/copilot-instructions.md	.github/ が存在する場合
Windsurf	.windsurf/rules/threadctx.md	.windsurf/ が存在する場合
Cline	.clinerules/threadctx.md	.clinerules が存在する場合
Gemini CLI	GEMINI.md	.gemini/ が存在する場合

共有ファイル（AGENTS.md、CLAUDE.md、Copilot、Gemini）には、マーカーで囲んだブロックを挿入し、その前後にある独自の内容は保持します。専用ファイルは全体が管理対象になります。これはプロジェクトでサーバーを初めて起動したときに自動的に行われるため、init を実行する必要はありません。 init を実行すると、この処理が明示的に開始され、結果が出力されます。どちらの場合も冪等です（安全に再実行でき、重複しません）。完全に無効にするには THREADCTX_NO_AUTO_RULES=1 を設定するか、init の呼び出しごとに --no-rules を指定します。

同じ指示は MCP の initialize ハンドシェイク自体の一部（プロトコルの instructions フィールド）としても送信されるため、ルールファイルがまだなくても、またプロジェクトのルールファイルをまったく読み込まないクライアントでも、モデルに届きます。ファイルベースのルールはその補強策です。すべての MCP クライアントが instructions を目立つ形で提示するとは限らないためです。

Claude Code のセットアップ

Claude Code の MCP 設定に追加します（claude mcp add を実行するか、~/.claude/mcp.json を直接編集してください）。

{
  "mcpServers": {
    "threadctx": {
      "command": "npx",
      "args": ["-y", "threadctx-mcp"],
      "env": {
        "THREADCTX_MODE": "cloud",
        "THREADCTX_API_KEY": "tctx_xxx"
      }
    }
  }
}

Cursor のセットアップ

プロジェクトのルートにある .cursor/mcp.json に同じブロックを追加します（または Cursor の「設定」→「ツールと MCP」から追加してください）。

{
  "mcpServers": {
    "threadctx": {
      "command": "npx",
      "args": ["-y", "threadctx-mcp"],
      "env": {
        "THREADCTX_MODE": "cloud",
        "THREADCTX_API_KEY": "tctx_xxx"
      }
    }
  }
}

これで完了です。MCP は移植性の高いオープンプロトコルなので、どちらのクライアントでも同じパッケージと設定を使用できます。

パッシブキャプチャ — git の履歴をメモリに変換

メモリの保存を、エージェントが memory_write を呼び出すことを覚えているかどうかに左右させるべきではありません。threadctx capture は前回の実行以降に取り込まれたコミットを読み込み、ご自身の LLM プロバイダーのキーを使って、再利用する価値のある判断や注意点を抽出します（些細なコミットは除外）。すでに保存されている内容との重複を取り除き、残ったものを書き込みます。特定のツールに依存しないため、作業が Claude Code、Cursor、Copilot、通常のエディターのどれで行われたかは関係ありません。

# Off by default because it calls an LLM (billed to your provider). Enable it:
export THREADCTX_CAPTURE_ENABLED=1
export ANTHROPIC_API_KEY=sk-...     # or OPENAI_API_KEY

npx threadctx-mcp capture --dry-run     # preview what it would store
npx threadctx-mcp capture               # store them (incremental since last run)
npx threadctx-mcp capture --since=v1.2.0 --diffs   # a range, with patches

# Scaffold a GitHub Action that captures every merged PR automatically:
npx threadctx-mcp capture --print-workflow > .github/workflows/threadctx-capture.yml

キャプチャは LLM プロバイダーを直接呼び出します。threadctx のサーバーを経由しないため、ローカルモードの「ご自身の LLM プロバイダー以外へのネットワーク呼び出しは行わない」という約束を守れます。THREADCTX_CAPTURE_ENABLED=1 を設定するか、1回限りの --force を指定しない限り無効なので、副作用としてトークン費用が発生することはありません。

環境変数

変数	必須	説明
THREADCTX_MODE	いいえ	local（デフォルト）または cloud
THREADCTX_API_KEY	cloud モードの場合のみ	cloud/scripts/create-tenant.ts を介して発行されます
THREADCTX_API_URL	いいえ	デフォルトは https://threadctx.dev/api/v1 です。セルフホストする場合は上書きしてください
THREADCTX_REPO	いいえ	git remote によるリポジトリの自動検出を上書きします
THREADCTX_DB_PATH	いいえ	ローカルモードの保存先パスです。デフォルトは ~/.threadctx/local.json です
THREADCTX_NO_AUTO_RULES	いいえ	サーバー起動時のエージェントルールファイルの自動挿入を無効にするには、1 を設定します
THREADCTX_CAPTURE_ENABLED	capture の場合	LLM を利用する capture コマンドを有効にするには、1 を設定します（デフォルトでは無効）
THREADCTX_CAPTURE_PROVIDER	いいえ	両方のキーが設定されている場合に anthropic または openai を指定します
THREADCTX_CAPTURE_MODEL	いいえ	抽出モデルを上書きします（デフォルト：Haiku / gpt-4o-mini）
ANTHROPIC_API_KEY / OPENAI_API_KEY	capture の場合	プロバイダーの独自キーです。capture はこのキーを直接使用します

ローカル開発

npm install
npm run dev     # runs the server via tsx, watches for changes
npm run build   # compiles to dist/ for publishing

ツールの仕組み

• memory_write(content, tags?) — エージェントは、分かりにくいバグを解決した後、アーキテクチャ上の決定を下した後、または記憶に値することを学んだ後に呼び出します。
• memory_query(task_description, max_results?) — エージェントは、リスクの高い作業や繰り返し行う作業を始める前に呼び出します。結果には一貫した帰属フッター（· via threadctx — shared team memory (N hits)）が付くため、Claude Code のターミナル出力でも Cursor のエージェントパネルでも、同じ文字列として認識できます。

ツールの説明は、モデルが memory_query を積極的に呼び出すよう促す内容になっています。また、0.3.0 以降は、セットアップ不要でサーバーがさらに 2 つの方法でこれを強化します。MCP の initialize 応答によって、接続するすべてのクライアントに同じ指示が伝えられ、初回起動時には CLAUDE.md / .cursor/rules/threadctx.mdc にも自動挿入されます。MCP ツールは依然として基本的にプル型であり（ツール呼び出しを強制する仕組みはありません）が、これら 3 つの層を組み合わせることで、実現可能な限り強い保証を提供します。

CLI サブコマンド

コマンド	内容
npx threadctx-mcp	MCP サーバーを実行します（Claude Code / Cursor が起動するものです）。プロジェクトでの初回起動時に、プロジェクトルールを自動挿入します。
npx threadctx-mcp init [--mode=cloud --api-key=…] [--no-rules]	チームで使うためにリポジトリをセットアップします。.threadctx.json、コミット可能な Claude Code/Cursor のプロジェクト MCP 設定、およびプロジェクトルールファイルを作成します。
npx threadctx-mcp join	チームメイトがすでにセットアップしたリポジトリに参加します。プロジェクト MCP 設定、ルール、およびクライアントごとの指示を設定します。
npx threadctx-mcp list [--all] [--full] [--json]	ローカルディスク上のメモリに保存されている内容を表示します。
npx threadctx-mcp capture [--dry-run] [--since=<ref>] [--max=N] [--diffs] [--model=ID] [--print-workflow]	独自の LLM キーを使って、最近の git 履歴をメモリに要約します。THREADCTX_CAPTURE_ENABLED=1 を設定するか --force を指定しない限り、無効です。

threadctx.dev/dashboard のダッシュボードでチーム（cloud）メモリを閲覧、検索、編集、整理できます。チーム API キーでサインインしてください。