cogmemory-mcp

CogMemory MCP Server

AI コーディングエージェント向けに、4 つのコンテキストサブシステムを提供する統合型のModel Context Protocolサーバーです。

1. メモリ — 決定事項、規約、エラー、アクティブなコンテキスト、変更履歴、計画、タスク、セッション
2. ナレッジグラフ — エンティティ、関係、観察事項
3. 仕様書 — 長文ドキュメント（PRD/SRS）。必要に応じて KG エンティティにリンクできます
4. コードグラフ — 静的な構造グラフ（シンボル／エッジ）＋名前付き実行トレース＋AI 生成アノテーション

ストレージにはbetter-sqlite3経由でSQLiteを使用します。デフォルトでは、クローンごとに~/.cogmemory/projects/以下に専用データベースが作成されます。

---

クイックスタート

インストール

オプション A — npx（推奨、常に最新版）：

npx -y cogmemory-mcp@latest

オプション B — グローバルインストール：

npm install -g cogmemory-mcp
cogmemory-mcp

オプション C — pnpm dlx：

pnpm dlx cogmemory-mcp@latest

オプション D — ソースからインストール（開発者向け）：

git clone https://github.com/skylarng89/cogmemory-mcp.git
cd cogmemory-mcp
pnpm install
pnpm run build

ネイティブモジュールの要件

CogMemory はbetter-sqlite3とtree-sitterに依存しており、インストール時にネイティブモジュールをコンパイルします。必要なものは次のとおりです。

• Python 3（node-gyp用）
• C/C++コンパイラ（Linuxではgcc／g++、macOSではXcode Command Line Tools、WindowsではVisual Studio Build Tools）
• make（Linux／macOS。通常は標準でインストールされています）

ほとんどのプラットフォームではビルド済みバイナリが利用できるため、通常は次の環境でコンパイルは省略されます。

• Linux x64 / arm64
• macOS x64 / arm64
• Windows x64

インストールに失敗した場合は、以下のトラブルシューティングを参照してください。

---

IDE／クライアントの設定

VS Code

.vscode/mcp.jsonに追加します（ワークスペース単位の設定）：

{
  "servers": {
    "cogmemory": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

または、マルチルート対応に--workspaceを使用します（必要になることはほとんどありません。ワークスペースの解決 — マルチルート対応を参照してください）。

{
  "servers": {
    "cogmemory-frontend": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest", "--workspace", "/path/to/frontend"]
    },
    "cogmemory-backend": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest", "--workspace", "/path/to/backend"]
    }
  }
}

ゼロ設定のデフォルト： --workspaceを省略すると、CogMemory は作業ディレクトリからプロジェクトを自動検出します（まず git ルートを検索し、次に最も近い.cogmemory/親ディレクトリを検索します）。すべてのプロジェクトでサーバーエントリは 1 つで十分です。各リポジトリには独自のメモリ領域が割り当てられます。--workspaceを指定するのは、モノレポ内のサブルートを対象にする場合に限ってください。

Cursor

.cursor/mcp.jsonに追加します。

{
  "mcpServers": {
    "cogmemory": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

Claude Desktop

~/.config/claude/claude_desktop_config.json（Linux／macOS）または%APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。

{
  "mcpServers": {
    "cogmemory": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

Claude Code

~/.claude/mcp.json（ユーザーレベル）または.claude/mcp.json（プロジェクトレベル）に追加します。

{
  "mcpServers": {
    "cogmemory": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

Cline

Cline 拡張機能の設定で、MCP サーバーを追加します。

• 名前： cogmemory
• コマンド： npx -y cogmemory-mcp@latest

または、cline_mcp_settings.jsonに追加します。

{
  "mcpServers": {
    "cogmemory": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

Windsurf

MCP 設定 → サーバーを追加：

{
  "mcpServers": {
    "cogmemory": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

OpenCode

opencode.jsonに追加します。

{
  "mcp": {
    "cogmemory": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

Zed

Zed の設定（settings.json）に追加します。

{
  "context_servers": {
    "cogmemory": {
      "binary": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

MCP Registry

CogMemory はMCP Registryに公開されています。Registry 対応クライアントでは、自動的に検出してインストールできます。

---

スコープ設定

CogMemory は次の優先順位でスコープを解決します。

1. ワークスペースのルートにある**.cogmemory/config.json**（プロジェクトレベルのオーバーライド）：

   { "scope": "project" }
   

2. 環境変数：COGMEMORY_SCOPE=project、global、またはworkspace

3. ユーザーレベルのフォールバック：~/.cogmemory/config.json（スコープ設定のみ）

4. デフォルト：project — クローンごとに~/.cogmemory/projects/以下にデータベースを作成します

デフォルトではクローンごとに分離されます。 各クローンには.cogmemory/config.json内で UUID が割り当てられ、データベースは~/.cogmemory/projects/memory-<project-id>.dbに保存されます。クローンを識別するのは UUID であり、フォルダー名やリポジトリの origin ではありません。従来の共有データベースを引き続き使用するには{ "scope": "global" }またはCOGMEMORY_SCOPE=globalを、リポジトリ内にデータベースを作成するには{ "scope": "workspace" }を使用してください。

パス

スコープ	データベースパス
project	~/.cogmemory/projects/memory-<project-id>.db
workspace	<workspace_root>/.cogmemory/memory.db
global	~/.cogmemory/global.db

アップグレードする場合： ワークスペースに既存の memory.db があり、設定ファイルがない場合、プロジェクトのデフォルト設定によってそのファイルが使用されないと、CogMemory は stderr に通知を記録します。引き続き使用するには、そのプロジェクトの .cogmemory/config.json に { "scope": "workspace" } を追加してください。COGMEMORY_SCOPE=global が明示的に選択されている場合は、global.db の既存データも引き続き利用できます。データが暗黙に再分割されることはありません。

---

プロジェクト ID

各プロジェクトには、.cogmemory/config.json の project_id に保存される安定した不透明なスラッグ（UUID）が割り当てられます。このスラッグがプロジェクトの ID であり、フォルダーのパスや名前は ID ではありません。すべてのメモリ（判断、規約、エラー、セッション、コードグラフなど）には、外部キーとして project_id が付与されます。そのため、次のことが可能です。

• 名前の変更や移動を安全に行えます。 プロジェクトフォルダーを移動しても、そのメモリへのアクセスは失われません。スラッグは設定ファイルとともに移動し、パスはメタデータとしてのみ扱われます。
• 固定パスの設定が機能します。 ${workspaceFolder} を展開できない IDE やクライアントでも、単一の共有データベースパスを指定できます。各プロジェクトのメモリはスラッグによって分離されたままです。
• プロジェクトスコープはクローンごとに分かれるのがデフォルトです。 クローンごとに別のデータベースを開くため、同時に動作するクライアントが、共有プロセスを無関係なプロジェクトの行に切り替えることはありません。
• グローバルスコープも引き続き利用できます。 ~/.cogmemory/global.db には複数のプロジェクトを格納でき、すべての読み取り／書き込みはアクティブなプロジェクトのスラッグで暗黙にスコープされます。

.cogmemory/config.json と Git

初回実行時にクローンごとに独自の ID が割り当てられるよう、.cogmemory/config.json は gitignore の対象にしてください。意図的にファイルをコピーまたはコミットすると、その UUID が共有されます。チャットを開始したり分岐したりしても、新しいプロジェクト ID は作成されません。

プロジェクト管理ツール

ツール	用途
list_projects	すべてのプロジェクトの行数、最終確認時刻、古さを示すフラグを表示します
rename_project	プロジェクトの表示ラベルを変更します（スラッグは変更できません）
prune_projects	プロジェクトとそのすべての行を完全に削除します（confirm が必要です）
switch_project	ワークスペースのルートから、実行時にアクティブなプロジェクトを再解決します

cogmemory_status は workspace_root、root_path_hint、resolution_source（override | git-root | dotcogmemory | cwd-fallback | runtime-switch）、active_project: { id, slug, label } を報告します。詳細モードでは、テーブルごとの行数も表示します。

実行時のプロジェクト切り替え

クライアントで固定された --workspace／cwd が実際に作業しているリポジトリと一致しない場合（たとえば、エージェントがセッション中に別のリポジトリを開いた場合）、対象リポジトリの絶対パスを指定して switch_project を呼び出してください。

{ "root_dir": "/mnt/repos/my-project" }

初期化が成功すると、対象ワークスペースに設定されたスコープ、データベース、UUID、数値のプロジェクト ID、ルートが一緒に切り替わります。ステータス、インデックス作成、ソーススニペットでは、新しいルートが使用されます。すでに実行中の非同期呼び出しは、元のコンテキストを使って完了します。無効なパス、破損した設定、データベースの初期化エラーが発生した場合も、以前のコンテキストは引き続き使用できます。

分岐したチャットと古い ID

新しいチャットまたは分岐したチャットの開始時：

1. cogmemory_status を呼び出し、workspace_root と実際のワークスペースを比較します。チャット履歴とキャッシュされた数値 ID は、正しい情報源ではありません。
2. ルートが異なる場合は、目的の絶対パスを指定して switch_project を呼び出し、その後、メモリを再取得します。クライアントのワークスペース不一致を解決するために、identity ファイルを削除しないでください。
3. ワークスペース UUID を再利用します。必要に応じて start_session で新しいメモリセッションを開始します。チャットの分岐は新しいプロジェクトではありません。

ツールの JSON レスポンスには project_identity: { id, slug, workspace_root } が含まれます。ツールは、読み取りや書き込みの前に古いコンテキストを拒否するための省略可能な expected_project_id を受け付けます。この値には UUID slug を指定します。特に、数値 ID が別々のデータベース間で一致する場合に便利です。PROJECT_MISMATCH が発生した場合は、ステータスを確認し、再試行する前に目的のルートへ切り替えてください。この省略可能なガードを使わない既存の呼び出しも引き続き利用できます。クライアントから正しい起動ルートも切り替え要求も提供されない場合、CogMemory はチャットが意図するワークスペースを推測できません。

メモリの書き込み時に指定された省略可能な古いセッション／プランの関連付けは、レスポンスの警告とともに無視されます。メモリはアクティブなプロジェクトに保存されます。明示的なセッションの読み取りと更新はプロジェクト単位で行われ、古いセッション ID に対しては復旧手順を含む not-found レスポンスが返されます。

過去の ID 不整合からの復旧

以前のプロジェクトスコープの起動処理では、memory-A.db を選択した後に、そのデータベースとワークスペース設定に UUID B を保存することがありました。現在の起動処理では、初期化全体で同じ UUID を維持し、並行する初期化を直列化し、設定変更をアトミックに反映します。

影響を受けた既存のストアについては、起動時にプロジェクトのデータベースを読み取り専用で調べます。保存されている ID が UUID または正確なワークスペースルートと一致する候補がちょうど 1 つの場合、そのデータベースを そのまま 再利用し、行 ID とメモリを保持します。設定では、既存のデータベースファイル名に含まれる UUID を project_database_id として記録します。この値は project_id と異なっていても問題ありません。データベースの名前変更、統合、削除は行われません。

一致する候補が複数ある場合は、PROJECT_IDENTITY_AMBIGUOUS が { databaseId, slug } のペアを一覧表示し、設定は変更されません。ほかの設定を保持したまま、.cogmemory/config.json で目的のペアを選択してください：

{
  "scope": "project",
  "project_id": "<slug from the selected candidate>",
  "project_database_id": "<databaseId from the same candidate>"
}

その後、MCP サーバーを再起動するか、すでに起動している場合は switch_project を再試行してください。選択したデータベースには、その UUID が含まれている必要があります。ほかの候補データベースも引き続き利用できます。分断された履歴の統合は、別途明示的に実行する操作です。

不正な JSON、無効な UUID、無効なローカルスコープの場合、ID が暗黙に置き換えられるのではなく、PROJECT_CONFIG_INVALID が返されます。バックアップから有効な設定を復元してください。初期化ロックの待機時間には上限があり、超過すると PROJECT_BUSY が報告されます。ロック保持中にプロセスがクラッシュした場合は、報告されたディレクトリの owner.json を調べ、所有者プロセスが終了したことを確認してから、放棄されたロックディレクトリのみを削除し、再試行してください。実行中のプロセスのロックは絶対に削除しないでください。

pnpm test:identity を実行すると、再起動／分岐時の継続性、並行プロセス、復旧、切り替え、古い ID、UUID ガード、実行中の呼び出しについて、分離された回帰テストを実行できます。

複数ルート／モノレポ

CWD から親ディレクトリをたどって検索する場合、Git ルートの検出は親ディレクトリの .cogmemory/ の検出より優先されます。モノレポでは、間違ったプロジェクトに気付かないまま紐付けられるのを避けるため、--workspace <path> または COGMEMORY_WORKSPACE で目的のルートを明示的に指定してください。

---

ワークスペースの解決とマルチルートのサポート

CogMemory は、次の優先順位でワークスペースのルート（ひいてはプロジェクトの識別アンカー）を解決します。

1. --workspace <path> CLI 引数（明示的な上書き、最優先）
2. COGMEMORY_WORKSPACE 環境変数（明示的な上書き）
3. Git ルート — CWD から上位にたどり、最も近い .git/ エントリを探します（Git リポジトリのデフォルトの判定基準）
4. CWD から上位にたどり、最も近い .cogmemory/ ディレクトリを含む親ディレクトリを探します
5. CWD にフォールバック

ほとんどのクライアントでは、設定は不要です。--workspace を指定せずに CogMemory を起動すると、クライアントの作業ディレクトリを含む Git リポジトリに接続します。そのため、各リポジトリには独自のプロジェクト ID が自動的に割り当てられます。

CogMemory は、ユーザーのホームディレクトリやファイルシステムのルートからプロジェクトを初期化することを拒否します。これにより、一般的なプロセスディレクトリから MCP サーバーを起動するクライアントが、誤ったプロジェクトの下にメモリを誤って保存するのを防ぎます。クライアントが正しい作業ディレクトリを指定できない場合は、ワークスペースを指定したエントリを設定するか、COGMEMORY_WORKSPACE にプロジェクトのルートをそのまま設定してください。

識別アンカーを Git ルートと異なる場所にする必要がある場合（たとえば、モノレポのサブディレクトリを独立したプロジェクトとして扱う場合）に限り、--workspace／COGMEMORY_WORKSPACE を固定してください。

cogmemory_status は、アクティブな workspace_root、root_path_hint、データベースのパス、UUID を報告します。明示的なワークスペースの上書きが無効な場合、無関係なディレクトリにフォールバックせず、エラーになります。

---

アップグレードと移行

CogMemory はバージョン管理された移行システムを使用します。新しいバージョンで列やテーブルが追加されると、次回のサーバー起動時に移行が自動的に実行されます。手動での操作は不要です。

初回の移行（v1.1.0 より前のデータベース）

古いスキーマを使用していた v1.1.0 より前のバージョンからアップグレードする場合：

1. バックアップファイルが自動的に作成されます：<db_path>.backup-pre-migrate-<timestamp>
2. 移行はトランザクション内で適用されます。いずれかの手順が失敗すると、データベースはロールバックされます
3. 問題が発生した場合は、バックアップから復元できます：cp memory.db.backup-* memory.db
4. バックアップを省略するには、COGMEMORY_SKIP_BACKUP=1 を設定してください（CI やディスク容量に制約のある環境など）

オプトアウト：アップデート確認のテレメトリー

デフォルトでは、CogMemory は新しいバージョンがあるかどうかを確認するため、24 時間に 1 回 npm レジストリをチェックします（check_for_updates ツールを使用）。これは registry.npmjs.org に対する読み取り専用の HTTPS GET で、パッケージマネージャーが行うものと同じリクエストです。

このチェックを無効にするには：

• 環境変数： COGMEMORY_DISABLE_UPDATE_CHECK=1
• 設定ファイル： .cogmemory/config.json に { "disable_update_check": true } を追加します

---

ツールのリファレンス（41 個のツール）

メモリツール（14）

ツール	説明
start_session	作業セッションを開始します（セッション ID を返します）
end_session	セッションを終了し、要約を保存します
get_session_summary	判断、エラー、変更履歴を含むセッションの詳細を呼び出します
remember_decision	根拠とタグを付けて判断を記録します
remember_convention	規約（デザイントークン、パターン、スタイル、命名）を記録または更新します
log_error	署名と解決方法を含むエラーを記録します
set_active_context	キーごとに現在の注目事項／タスクを登録または更新します
get_active_context	キーごとに現在の注目事項を読み取ります
log_change	変更履歴の項目を追加します
add_plan_item	ロードマップの項目を追加します
update_plan_status	計画項目のステータスを変更します
create_task	タスクを作成します。必要に応じて計画に関連付けられます
update_task_status	タスクのステータスを変更します
recall	判断／規約／エラー／変更履歴を横断して一括検索します

ナレッジグラフツール（4）

ツール	説明
create_entity	エンティティを追加します（名前と種類が同じ場合は重複を除外します）
create_relation	2 つのエンティティを型付きの関係で結び付けます
add_observation	エンティティに事実を追加します
search_knowledge	エンティティ、関係、観察事項を検索します

仕様ツール（3）

ツール	説明
create_spec	長文ドキュメントを保存します
get_spec	ID または完全一致するタイトルで取得します
update_spec	内容／タイトルを更新し、バージョンを自動的に繰り上げます

コードグラフツール（4）

ツール	説明
index_codebase	ワークスペースを走査し、シンボルとエッジを抽出します（JS/TS は ts-morph、Python は tree-sitter を使用します）
query_code_graph	シンボルの呼び出し元／呼び出し先／インポートを検索します（1 ホップ）
generate_codemap	エントリーシンボルから BFS を行い、任意のトレースと注釈を含む範囲を限定したサブグラフを生成します
annotate_symbol	シンボルまたはトレースに説明文を追加します

イントロスペクションツール（2）

ツール	説明
cogmemory_status	実行時設定を表示します。パッケージのバージョン、スキーマのバージョン、DB パス、ワークスペースのルート、スコープ、インデックスのカバレッジ、サブシステムの件数が含まれます
check_for_updates	npm で新しいバージョンが公開されているか確認します（レジストリへの HTTPS GET。結果は 24 時間キャッシュされます）

コード分析ツール（8）

ツール	説明
semantic_code_search	TF-IDF ベースのセマンティックコード検索です。自然言語でクエリを入力すると、関連度順にシンボルを返します。
find_dead_code	エクスポートされたシンボルと設定可能なエントリポイントを除外し、呼び出し元が 0 件のシンボルを検索します。
find_duplicates	完全ハッシュと MinHash 類似度によって重複・クローンのシンボルペアを検出し、SIMILAR_TO エッジを挿入します。
find_related	共通の呼び出し元・インポート・同一ファイルのヒューリスティクスを用いて、意味的に関連するシンボルを検出し、SEMANTICALLY_RELATED エッジを挿入します。
query_graph	再帰的 CTE を使った複数ホップの構造グラフクエリです。任意の深さ、エッジタイプのフィルター、方向に対応しています。
analyze_impact	未コミットの変更（git diff）の影響を分析します。変更されたファイルをシンボルに対応付け、逆方向の推移的な呼び出し元の閉包を計算します。
get_code_snippet	ID または名前でシンボルを指定してソースコード行を取得します。前後のコンテキスト行も任意で追加できます。
check_index_coverage	インデックス済み・未インデックス・古いファイルを、言語ごとの内訳とともに報告します。

一覧表示・削除ツール（5）

ツール	説明
list_items	任意のサブシステムに保存されたエントリを、任意のフィルターで参照します。
delete_item	任意のサブシステムから、ID を指定して 1 行を削除します。
delete_by_key	文字列キーを指定してコンテキストエントリを削除します。
delete_by_path	コードグラフの file_index からファイルを削除します。
purge_subsystem	サブシステムのすべての行を削除します（confirm=true が必要です）。

プロジェクトツール（4）

ツール	説明
list_projects	すべてのプロジェクトを行数と古さのフラグとともに一覧表示します。アクティブなプロジェクトには印が付きます。
rename_project	プロジェクトの表示ラベルを変更します（スラッグは変更できません）。
prune_projects	プロジェクトとそのすべての行を完全に削除します（confirm=true が必要です）。
switch_project	ワークスペースのルートから実行時にアクティブなプロジェクトを再解決します（失敗時は閉じる動作）。

---

アーキテクチャ

cogmemory-mcp/
├── src/
│   ├── index.ts                 # entry point, server bootstrap
│   ├── version.ts               # auto-generated version constant
│   ├── config.ts                # scope resolution, path resolution
│   ├── update-check.ts          # fail-safe startup update notifier (update-notifier)
│   ├── types.ts                 # shared TS types mirroring schema
│   ├── db/
│   │   ├── connection.ts        # DB open/close, pragma setup
│   │   ├── migration-runner.ts  # versioned migration engine (PRAGMA user_version)
│   │   ├── migrate.ts           # legacy idempotent migration (deprecated)
│   │   └── migrations/
│   │       ├── 001_baseline.sql         # full v1 schema
│   │       ├── 002_symbol_export_hash.sql
│   │       ├── 003_index_errors.sql
│   │       ├── 004_symbol_embeddings.sql
│   │       ├── 005_edge_metadata.sql
│   │       ├── 006_symbol_tokens.sql
│   │       ├── 007_symbol_minhash.sql
│   │       ├── 008_project_scoping.sql
│   │       └── 009_project_scoped_uniques.sql
│   ├── tools/
│   │   ├── memory.ts            # decisions/conventions/errors/context/changelog/recall
│   │   ├── plan-tasks.ts        # plan + tasks tools
│   │   ├── sessions.ts          # start/end session, summary
│   │   ├── knowledge-graph.ts   # entities/relations/observations
│   │   ├── specs.ts             # spec CRUD
│   │   ├── code-graph.ts        # index_codebase, query_code_graph
│   │   ├── codemap.ts           # generate_codemap, annotate_symbol
│   │   ├── code-analysis.ts     # dead code, duplicates, related, graph query, impact, snippet, coverage, search
│   │   ├── introspection.ts     # cogmemory_status, check_for_updates
│   │   ├── list-delete.ts       # list_items, delete_item, purge_subsystem
│   │   └── utils.ts             # wrapHandler, jsonOk, jsonFail, jsonErr
│   └── indexing/
│       ├── ts-analyzer.ts       # ts-morph symbol/edge extraction (JS/TS)
│       ├── py-analyzer.ts       # tree-sitter symbol/edge extraction (Python)
│       ├── edge-types.ts        # edge type constants (calls, imports, extends, implements, similarto, semrelated)
│       └── walker.ts            # file discovery, gitignore respect
├── package.json
├── tsconfig.json
└── README.md

---

スキーマ（25 テーブル）

基本テーブル（21）：

• メモリ（8）： sessions、decisions、conventions、errors、context、changelog、plan、tasks
• ナレッジグラフ（3）： entities、relations、observations
• 仕様（1）： specs
• コードグラフ（5）： symbols（is_exported、body_hash、token_count 列を含む）、edges（metadata JSON 列を含む）、execution_traces、codemap_annotations、file_index
• コード分析（3）： index_errors、symbol_tokens（TF-IDF）、symbol_minhash（MinHash シグネチャ）
• 今後の機能（1）： symbol_embeddings（スタブ — フェーズ 2 向けのベクトル埋め込み）

FTS5 テーブル（4）：

• Recall FTS： recall_docs（コンテンツテーブル）＋ recall_fts（FTS5 仮想テーブル）— recall を支えます
• ナレッジグラフ FTS： kg_docs（コンテンツテーブル）＋ kg_fts（FTS5 仮想テーブル）— search_knowledge を支えます

スキーマのマイグレーションは PRAGMA user_version によって自動的に行われます（現在のバージョンは 9 です）。

---

対応言語

コードグラフ（index_codebase）は、言語ごとのアナライザーを使用して、ソースファイルからシンボルとエッジを抽出します。

言語	拡張子	アナライザー	抽出されるシンボル
TypeScript	.ts, .tsx	ts-morph	ファイル、関数、クラス、インターフェース、メソッド、型エイリアス、列挙型、変数（is_exported を含む）
JavaScript	.js, .jsx, .mjs, .cjs	ts-morph	ファイル、関数、クラス、メソッド、変数
Python	.py	tree-sitter	ファイル、関数、クラス、メソッド（__all__／アンダースコアルールによる is_exported を含む）

構造エッジ： calls、imports、extends、implements

解析エッジ： similarto（クローン検出）、semrelated（意味的な関係の検出）

---

プラグマ

接続を開くたびに設定します。

PRAGMA journal_mode = WAL;
PRAGMA foreign_keys = ON;

---

開発

pnpm run dev        # Run with tsx (no build step)
pnpm run build      # Compile TypeScript (regenerates version.ts via prebuild)
pnpm run start      # Run compiled output
pnpm run inspect    # Launch MCP Inspector
pnpm run smoke-test # Run smoke test script (43 checks)

---

トラブルシューティング

ネイティブモジュールのビルド失敗

npm install または pnpm install が node-gyp エラーで失敗する場合：

1. Python 3 をインストールします： python3 --version を実行し、インストールされていない場合はパッケージマネージャーからインストールします
2. C++ ビルドツールをインストールします：
   • macOS： xcode-select --install
   • Ubuntu/Debian： sudo apt-get install build-essential
   • Windows： 「C++ build tools」ワークロードを含む Visual Studio Build Tools をインストールします
3. 再試行します： npm rebuild better-sqlite3（または npm rebuild tree-sitter）

マイグレーションの失敗

サーバーがマイグレーションエラーで終了する場合：

1. stderr でエラーメッセージとマイグレーションファイル番号を確認します
2. バックアップから復元します：cp .cogmemory/memory.db.backup-* .cogmemory/memory.db
3. 再試行します。マイグレーションは現在の user_version から再実行されます

大規模ワークスペースのパフォーマンス

5万個以上のファイルがあるワークスペースの場合：

1. .gitignore を使用して、ベンダー提供コードや生成コードを除外します（CogMemory はこれを尊重します）
2. ウォーカーはデフォルトで node_modules、.git、dist、build、.next、.cogmemory、__pycache__、.venv、venv、*.min.js、*.min.css、*.map をスキップします
3. インデックスの網羅状況：check_index_coverage ツールは、インデックス未作成ファイルのレポートを1,000件ずつページ分割して返します

analyze_impact — git が利用できない場合

ワークスペースが git リポジトリではない場合、自動検出を使った analyze_impact は失敗します。代わりに changed_files を手動で渡してください。

---

ライセンス

MIT

リリースのワークフローと復旧

.github/workflows/publish.yml では、4つのジョブを個別に実行します。

ジョブ	作業内容	再実行時の動作
ビルドと検証／復旧の準備	タグと package.json の整合性を検証し、レジストリのメタデータを同期して、ビルド、スモークテスト、識別情報テストを実行し、パッケージを1回作成します	この実行試行に固有のアーティファクトをアップロードします
npm に公開	アーティファクトの完全性を検証してから、OIDC／プロビナンスを使用して tarball を公開します	npm のメタデータと tarball の完全性が一致するリリースがすでに存在する場合に限り、スキップします
MCP Registry に公開	対象の npm バージョンが公開されるまで待機し、OIDC で認証して登録します	一致する登録がすでに存在することを検証し、一時的な公開エラーは再試行します
リリースの概要	実際のジョブ結果と公開出力を読み取ります	失敗またはスキップしたジョブを報告し、npm への登録と公開確認済みの状態を区別します

pnpm ストアのキャッシュキーにはロックファイルが使用されます。node_modules はランナー間で共有されません。承認済みのネイティブ依存関係はビルドランナー上でビルドされます。検証済みの tarball、同期済みの server.json、リリースマニフェストは、30日間保持されるワークフローアーティファクトとして転送されるため、MCP ジョブだけを再実行しても npm の再ビルドや再公開は行われません。固定された MCP パブリッシャーアーカイブは、バージョン、OS、アーキテクチャ、チェックサムをキーにキャッシュされ、復元のたびにチェックサムが検証されます。レジストリへの登録前にこのキャッシュを保存するため、レジストリのエラーによってキャッシュが失われることはありません。

通常のリリース

1. 対象のバージョンをコミットし、それに一致する vX.Y.Z タグをプッシュします。タグは package.json と一致している必要があります。一致しない場合、ワークフローはエラーになります。
2. ビルドジョブで smoke-test と test:identity を両方実行し、ソースコミットをパッケージのメタデータに記録して、テスト済みのビルドをパッケージ化します。
3. npm への公開では、ライフサイクルビルドを再実行せずに、その tarball を登録します。登録が成功しても、処理中の場合があります。
4. MCP ジョブでは、公開されている npm のバージョンを15秒ごとに最大10分間確認します。認証エラーやリリース内容の不一致はすぐにエラーになります。レジストリの停止や一時的な MCP 公開エラーには、回数を制限して再試行します。

公開権限は npm ジョブと MCP ジョブに限定されています。既存の信頼済みパブリッシャーのワークフロー ID を維持するため、ワークフローファイル名は publish.yml のままです。npm の latest タグへの更新が重複しないよう、リリースは引き続き直列化されます。

失敗したステージを再実行する

新しいワークフローを使用する実行の場合は、GitHub Actions で実行を開き、Re-run failed jobs を選択するか、Publish MCP Registry ジョブのみを再実行します。成功した上流ジョブとそのアーティファクトは再利用されます。アーティファクトの有効期限が切れている場合は、新しい手動実行を開始してください。すべてのジョブを再実行すると、既存の npm リリースが検証され、上書きは試みられません。同じバージョンに異なる内容がある場合は、安全にエラーになります。

v1.15.0 を含む過去のリリースを復旧する

このワークフローの変更がデフォルトブランチに反映されたら、次の手順を実行します。

1. Actions → Publish Package → Run workflow を開きます。
2. ワークフローの実装に使用するデフォルトブランチを選択します。
3. v1.15.0 などの既存のリリースタグを入力し、mcp-only を選択します。
4. ワークフローを実行します。現在のリリースヘルパーを読み込み、選択したタグをメタデータ用にチェックアウトしたうえで、依存関係のインストール、パッケージのビルド、npm への公開をスキップします。

MCP のみの復旧では、登録前に、npm のパッケージ名、バージョン、MCP 名、リポジトリ、gitHead が選択したタグと一致することを検証します。ソースコミットを検証できない場合はエラーになります。古いタグの server.json のバージョンは、そのタグの package.json に合わせて同期されます。タグを移動したり、公開済みパッケージを変更したりすることはありません。異なるメタデータを持つ既存の MCP バージョンや、非アクティブなステータスのバージョンについては、自動的に置き換えず、調査が必要です。

過去の元のワークフロー実行を再実行すると、当時のワークフロー定義が引き続き使用されます。新しいロジックで過去の実行を復旧するには、この手動の復旧手順を使用してください。

ローカルのリリースヘルパーのチェック

node --test scripts/release.test.mjs

これらのテストでは、一時的な成果物とモック化したレジストリ／コマンドを使用し、公開処理は行いません。テストでは、公開反映までの遅延、リクエストの失敗、既存のバージョン、整合性の不一致、ソースコミットの検証、再試行の上限、サマリーの正確性を確認します。ホスト型 OIDC と公開には、実際の GitHub Actions の実行が引き続き必要です。