Conventions MCP

conventions-mcp

永続的なコーディング規約や継続的な指示を保存する個人用メモリです。1つのストアを、MCP 互換のあらゆる AI クライアントから、すべてのプロジェクトで利用できます。「この言語では常にインデントを2スペースにする」「main への強制プッシュは絶対にしない」といったルール、長く役立つ修正事項、今後のセッションにも引き継ぐべき継続的なワークフローの好みを保存します。その都度、毎回説明し直す必要はありません。個々の作業の履歴や、タスク固有の指示、一時的な決定、現在の状況、一度限りのコマンドを記録する場所ではありません。

このツールを選ぶ理由

メモリ MCP サーバーには事欠きません。すでに定評のあるもの（mem0/OpenMemory、Zep/Graphiti、公式のリファレンスメモリサーバーのほか、多数の小規模プロジェクト）が、「セッションをまたいで情報を記憶する」機能を提供しています。このツールの特徴は次のとおりです。

• 汎用的なメモ帳ではなく、限定的な分類体系を採用。 すべての記録は今後の作業に役立つ永続的なルールでなければならず、目的に特化した5種類（規約、指示、修正、好み、その他）のいずれかに分類され、プロジェクト欄とトピックタグが付与されます。タスク固有の手順や作業履歴は対象外にすることで、検索結果がノイズに埋もれず、正確さを保てます。
• 最善努力に頼らない、確実な取得。 ほとんどのメモリ MCP は、呼び出し元のモデルがツールの説明を見て関連性に気付き、呼び出すかどうかを判断する仕組みだけに頼っています。この方法では、呼び出しが行われなかったことに気付けず、動作も一貫しません。Codex と Claude Code のフックは、エージェントに list_rules の呼び出しを強制します。SessionStart が指示を提供し、PreToolUse はその呼び出しが行われるまで、ほかのすべてのツールを拒否します。
• デフォルトで透明性を確保し、黙って処理しない。 記録や更新を行うたびに、保存された内容を一字一句そのまま、グローバルかプロジェクト限定かとあわせて直ちに返します。聞き間違いや分類ミスがあれば、その場で気付いて修正できます。検索して3セッション後に初めて気付く、といったことはありません。
• 実行時は完全ローカル。 SQLite とローカルの埋め込みモデルを使用します。ホスト型サービス、トークンごとの料金、API キーは不要です。埋め込みモデルは初回使用時（または conventions-mcp warmup の実行時）に一度だけダウンロードされ、その後はローカルで動作します。分類（type/topics/projectScoped）は記録時に呼び出し元のエージェントが行い、ツールの説明がその判断を助けます。エージェントは、その情報が生まれた会話全体をすでに把握しているため、独立した抽出モデルに単独の内容文字列を渡すより豊富な文脈を利用できます。
• 曖昧な照合なしでプロジェクトごとに適用。 ルールはグローバル（デフォルト）にすることも、特定のコードベースに関連付けることもできます。Stdio クライアントでは作業ディレクトリからプロジェクトを特定し、HTTP クライアントでは MCP ルートまたは X-Conventions-Project ヘッダーを指定します。LLM が自由記述からプロジェクト識別子を推測することはありません。

汎用的な「何でも記憶する」ストアを探している場合や、Claude Code を使っておらず、フックによる確実な動作も必要ない場合は、上記のより汎用的な選択肢のほうが適しているかもしれません。このツールは、コーディング規約に特化した、正確さを保ち、モデルが確認を忘れないよう信頼する必要のないメモリを求める人のためのものです。

保存するよう調整されている内容

呼び出し元のエージェントは、capture_thought のツール説明（src/server.js）に基づいて、各記録を次の5種類のいずれかに分類します。

種類	意味
convention	特定のコーディングスタイルやパターンに関するルール（例：「インデントには常に2つのスペースを使う」）
instruction	作業方法や振る舞いに関する継続的な指示（例：「main への強制プッシュは絶対にしない」）
correction	今後の振る舞いに対する恒久的な修正
preference	厳格なルールではない、長期的な好み
other	上記4種類に当てはまらない、その他の永続的で将来に関わるルール

各思考には、フィルタリング用のトピックタグも1～3個付与されます。これは意図的に用途を絞ったもので、一般的なメモ保存機能ではありません。ただし、分類体系はハードコードされたロジックではなく、src/server.js にあるツール説明とその zod スキーマの文言だけで定義されています。convention と instruction の分類基準を調整したり、新しい種類を追加したりするには、コードを再構成するのではなく、その説明文を編集します。注意点が1つあります。5種類の名前は list_thoughts の type フィルターの列挙型でも参照されています（src/server.js）。種類の名前を変更したり追加したりする場合は、新しい種類がフィルター値として拒否されないよう、その列挙型も更新してください。データはすべて JSON ブロブの列に保存されるため、スキーマの移行は必要ありません。

各思考にはプロジェクトフィールドがあります。null はすべての場所に適用されることを示し、それ以外の場合は path: を先頭に付けた正規化済みの絶対パスです。区切り文字はそのまま保持されるため、/work/a-b と /work/a/b は異なるプロジェクトを示します。呼び出し元のエージェントが判断するのは、ルールをプロジェクトに限定するかどうかだけです。既存のハイフン区切り ID からの移行には、upgrading.md に記載された、バックアップを最初に行う明示的な移行手順が必要です。

• ストレージ： SQLite（better-sqlite3）と、ネイティブなベクトル検索用の sqlite-vec、キーワード検索用の FTS5 を使用し、相互順位融合で組み合わせます。ファイルは1つだけで、サーバーもデーモンも必要ありません。
• 埋め込み： Xenova/bge-small-en-v1.5（384次元、量子化済み、約130MB）を使用し、ローカルで実行します。~/.conventions-mcp/models に一度だけダウンロードされ、必要に応じて読み込まれます。GPU は不要です。
• 分類： 記録時に、ツール説明に基づいて呼び出し元のエージェント（Claude Code または任意の MCP クライアント）が行います。ネットワーク呼び出し、外部モデル、API キーは必要ありません。
• トランスポート： デフォルトでは stdio 経由の MCP を使用します。永続サービスとして実行するための、オプションの localhost 限定 Streamable HTTP モードも利用できます。
• 先回りした検索： Codex と Claude Code のフック（以下を参照）が、コンテキストの境界ごとに継続的なルールを読み込むか適用します。同期を保つためのプロジェクト指示ファイルは不要で、ツールの説明が関連するとモデルが気づくことにも依存しません。
• スコープを限定した検索： list_rules とセマンティック検索では、グローバルルールと現在のプロジェクトのルールが返されます。他のコードベースに固有のルールは、通常の検索結果には含まれません。list_thoughts は、引き続きすべてのレコードを管理するための明示的なビューです。

セットアップ

AI コーディングエージェントを使ってインストールしますか？ このリポジトリを渡し、正規のインストールとクライアント統合の手順書に従うよう依頼してください。 手順書では、パスの特定、設定の上書きではなくマージ、実際の記録・一覧表示・削除による受け入れテスト、およびテスト記録の削除が必要です。

入手方法は、ソースを読み取ったり変更したりする場合は Git チェックアウト、実行するだけの場合は npm パッケージの 2 通りです。

Git チェックアウト：

npm install
npm run init-db        # creates data/memory.db

npm パッケージ：

npm install -g conventions-mcp --onnxruntime-node-install-cuda=skip
conventions-mcp init-db    # creates ~/.conventions-mcp/memory.db
conventions-mcp warmup     # downloads and verifies the embedding model

API キーや外部サービスは不要です。データベース、モデルキャッシュ、トランスポート、タイムアウトのオプション設定は .env.example に記載されています。

インストール済みのコマンドを確認するには conventions-mcp --help を、PATH 上のリリースを確認するには conventions-mcp --version を使用してください。ローカルの信頼モデルと非公開の報告手順については、SECURITY.md を参照してください。 ダウンロードを行わずに、ランタイム、データベース、権限、ベクター拡張機能、モデルキャッシュの準備状況を確認するには、conventions-mcp doctor を実行してください。 フォーマットメタデータのないレガシーデータベースには、バックアップを先に作成してから conventions-mcp migrate-storage <absolute-backup-path> コマンドを実行する必要があります。互換性のないことが明示されたフォーマットは推測で処理せず、拒否されます。

ローカル常駐サービス

MCP クライアントがセッションごとに stdio の子プロセスを起動するのではなく、起動時に管理される単一のサーバーに接続する場合は、Streamable HTTP を使用してください。

MCP_TRANSPORT=http MCP_HTTP_HOST=127.0.0.1 MCP_HTTP_PORT=47123 conventions-mcp

このコマンドを OS のサービスマネージャーで実行し、MCP クライアントを http://127.0.0.1:47123/mcp に設定してください。systemd、launchd、Windows の完全なセットアップおよび確認手順については、docs/shared-service.md を参照してください。サーバーは localhost にバインドされている場合、ローカル以外の Host ヘッダーを拒否します。MCP_HTTP_HOST のデフォルトは 127.0.0.1、MCP_HTTP_PORT のデフォルトは 47123 です。 このサービスは、ループバックの準備状況確認用に GET /healthz を公開し、MCP_HTTP_MAX_SESSIONS（デフォルトは 100）と MCP_HTTP_SESSION_IDLE_MS（デフォルトは 30 分）によって保持するセッション数を制限します。

MCP roots をサポートする HTTP クライアントには、追加のプロジェクト設定は不要です。サポートしないクライアントでは、プロジェクトローカルの MCP 設定で X-Conventions-Project にプロジェクトの絶対パスを設定してください。どちらの値も指定されていない HTTP セッションにはグローバルルールのみが提供され、プロジェクト単位の記録を作成できません。これにより、あるプロジェクトのルールが別のプロジェクトに漏れることを防ぎます。

Codex では、アクティブなワークスペースを動的に共有 HTTP サーバーに渡すことができます。

[mcp_servers.conventions]
url = "http://127.0.0.1:47123/mcp"
http_headers_helper = "conventions-mcp codex-project-header"

Codex はアクティブなワークスペースでヘルパーを実行します。サーバーはその絶対パスを正規化し、プロジェクト識別子の先頭に path: を付けます。

Claude Code に登録する

1 つのリポジトリだけでなくすべてのプロジェクトで利用できるよう、ユーザースコープで登録してください。手作業で設定ファイルを編集せず、claude mcp add CLI を使用します。

# Git checkout — an absolute path, since Claude Code may spawn this from an
# arbitrary working directory:
claude mcp add --scope user conventions -- node /absolute/path/to/conventions-mcp/src/server.js

# npm package — already on PATH:
claude mcp add --scope user conventions -- conventions-mcp

いずれの方法でも、~/.claude.json の mcpServers キーに書き込まれます。CLI が実際に読み取るのはこちらです。~/.claude/settings.json に直接配置した mcpServers エントリは、何も通知されず無視されます。claude mcp list で確認してください。新しく登録したサーバーを認識させるには、Claude Code の新しいセッションが必要です。

Codex の常設ルールフック

hooks/hooks.json には、ユーザー単位の Codex SessionStart フックと PreToolUse フックが含まれています。最初のフックはエージェントに list_rules を呼び出すよう指示し、2 つ目はその呼び出しが行われるまで、ほかのすべてのツールを拒否します。このゲートは、復元された会話に以前のルール読み込みが含まれていても、起動、再開、/clear、コンパクションのたびに再設定されます。ルール自体はフックの出力には含まれないため、大量のルールが MCP ツールからエージェントに渡される前に切り詰められることはありません。

~/.codex/hooks.json にインストールしてください。このファイルにすでにフックが含まれている場合は、既存の設定を置き換えるのではなく、このファイルの SessionStart と PreToolUse の項目を統合してください。このフックは、上記のセットアップコマンドと同じく、MCP サーバーが conventions として登録されていること、およびインストール済みの conventions-mcp コマンドが PATH にあることを前提とします。Codex で /hooks を一度開き、新しくインストールしたフックを確認して信頼してください。起動フックが実行されるには、新しいセッションが必要です。

Claude Code の常設ルールフック

チェックアウトを使うユーザーは、Codex のフックでも Node の絶対パスと bin/cli.js のパスを指定して呼び出せます。インストール方法を参照してください。npm のグローバルコピーは必要ありません。フックゲートは、失敗した場合も含め、list_rules の呼び出しを試みた時点で解除されます。ただし、呼び出し元のエージェントは引き続き失敗に対処し、ルールを取得する必要があります。

~/.claude/settings.json の 3 つのフックは、ツールを使う前に list_rules を実行するよう徹底します。最初の 2 つはリマインダーを表示し、3 つ目が実際に実行を制御します。

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "node /absolute/path/to/conventions-mcp/bin/session-rules.js", "timeout": 15 }] }
    ],
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "node /absolute/path/to/conventions-mcp/bin/prompt-reminder.js", "timeout": 5 }] }
    ],
    "PreToolUse": [
      { "matcher": "*", "hooks": [{ "type": "command", "command": "node /absolute/path/to/conventions-mcp/bin/pre-tool-check.js", "timeout": 5 }] }
    ]
  }
}

• bin/session-rules.js はセッション開始時に実行され、まず list_rules を呼び出すよう簡潔なリマインダーを表示します。ルールの内容をフックの出力に直接埋め込む方法は、拡張性に欠けるため採用していません（保存されたルールが十分に多いと、モデルに届く前に小さなプレビューへ黙って切り詰められます）。再開、コンパクション、/clear を含め、呼び出しのたびに実行ゲートが再設定されるため、以前の読み込みによって新しい指示を回避することはできません。
• bin/prompt-reminder.js は各ターンで実行され、読み込まれた規約に従うことと、将来のセッションや繰り返し行う作業に必要な、本当に永続性のあるルールだけを記録することを静的なリマインダーで通知します。タスク固有の指示、一時的な選択、現在の状況、インシデントの履歴、1 回限りのコマンド、個々の作業をどのように完了したかの記録は、明示的に対象外としています。
• bin/pre-tool-check.js は各ツール呼び出しの前に実行され、このセッションで list_rules が実行されるまで呼び出しを完全に拒否します。最初の 2 つのフックは助言のみ（リマインダーのみ）を行うため、このフックが要件を実際に適用する層です。これはターンごとではなく、セッションごとに 1 回強制されます。

3 つのフックはいずれもデータベースに直接アクセスしません。list_rules は、stdio の作業ディレクトリ、MCP ルート、または HTTP プロジェクトの X-Conventions-Project ヘッダーから現在のプロジェクトを解決します。

**npm パッケージ：**スクリプトは既知のクローンパスではなくグローバルインストール先にあるため、まず npm root -g で場所を特定し、同様に $(npm root -g)/conventions-mcp/bin/session-rules.js をフックに指定してください。

Windows：.js ファイルを直接指定する代わりに、command には .cmd ラッパーを指定してください（node のプレフィックスは不要です。バッチファイルが呼び出します）。Git のチェックアウトでは bin\session-rules.cmd / bin\prompt-reminder.cmd / bin\pre-tool-check.cmd を、npm パッケージでは npm root -g 以下の同等のパスを指定してください。

ツール

ツール	説明
capture_thought	慣習、指示、修正、または好みを保存します。ローカルで埋め込みを行います。分類は呼び出し元のエージェントが指定します。
update_thought	既存の思考をその場で修正・調整します。同じ ID を使用し、新しい内容で再埋め込みと再タグ付けを行います。
search_thoughts	セマンティック検索とキーワード検索を組み合わせたハイブリッド検索を行います。
list_thoughts	すべての記録を一覧表示します。種類による絞り込みも可能です。
list_rules	すべてのグローバルルールと現在のプロジェクトのルールを、決定論的な単一の呼び出しで取得します。埋め込みも順位付けも行わず、ID 順に並べます。フックが内部で使用する機能です。
thought_stats	合計数、種類別の内訳、上位トピック、プロジェクトごとの件数を表示します。
delete_thought	ID を指定して思考を完全に削除します。

注意事項

• バックアップを先に行うアップグレード、レガシーベクトルの移行、保護された復元、ロールバックについては、docs/upgrading.md に従ってください。

• 1 つのメッセージに複数の異なるルールが含まれている場合、ルールごとに個別に伝達し、まとめて 1 件として記録したり要約したりせず、capture_thought を 1 回ずつ呼び出します。

• データベースは、Git チェックアウトでは data/memory.db に、npm パッケージでは ~/.conventions-mcp/memory.db に保存されます（どちらも MEMORY_DB_PATH で変更できます）。このファイルは Git の追跡対象外で、プライベートなアクセス権限で作成されます。稼働中のデータを安全にバックアップするには、整合性チェック付きの conventions-mcp backup <absolute-destination> を使用してください。スケジュール設定については、docs/shared-service.md を参照してください。

• 埋め込みモデルと次元は src/storage-format.js で宣言されています。 モデルを変更する場合は、既存のルールを再埋め込みする明示的なストレージ移行が必要です。定数だけを変更すると、既存のストアとの互換性が失われます。