Codemesh

問題

AI コーディングエージェントは、トークンの 40～80% を情報探索に費やしています — ファイルを grep し、無関係なコードを読み、以前のセッションで把握したコンテキストを再構築しています。

600 ファイルのコードベースでは、典型的な調査タスクで、何が関連するのかをエージェントが把握する前に、10 個以上のファイルを読み込むことになります。

Before:  Agent → Grep → 50 matches → Read 10 files → Understand → Work
After:   Agent → codemesh_map → expand chosen branches → read exact symbols → Work

Codemesh は、エージェントに永続的でクエリ可能なナレッジグラフを提供する MCP サーバーです。グラフは時間とともに賢くなります。エージェントが学んだことを書き戻すため、次のセッションは情報を把握した状態で始められます。

ベンチマーク

Claude Sonnet 4.6 を使用し、実際の 6 つのコードベース（Alamofire、Excalidraw、VS Code、Swift Compiler、pydantic-validators、pydantic-basemodel）でベンチマークを実施しました。ベースラインおよびコンテキスト向けのグラフベースの手法と比較しています。

全手法、リポジトリごとの内訳、ペアごとの比較については、docs/benchmark-results.md | 初期の pydantic 評価をご覧ください。

これらの過去の実行では、以前の回答優先ワークフローを使用しました。以下で説明するマップ優先のナビゲーションワークフローは、探索的な Pydantic パイロット評価で評価しています。このセクションの数値を、その測定性能として解釈しないでください。

コスト

時間

ツール呼び出し（エージェントのターン数）

品質（1～10、LLM-as-judge）

コスト削減：Codemesh MCP とベースラインの比較

メモ

Codemesh MCP は、テストしたすべてのモードの中で最も低コストかつ最速です。6 つのリポジトリ全体の平均で、ベースラインより 71%低コスト、72%高速であり、ツール呼び出し回数も82%少なくなっています（8 回対45回）。品質はベースラインと同等です（7.9対7.0）。品質では Codegraph が Codemesh を上回ります（8.4）が、コストは約2倍です（$0.45対$0.22）。以前の codemesh ビルドで性能が低下した、理解に重点を置くクエリ（Excalidraw、pydantic-basemodel）を含め、すべてのリポジトリでコストと時間を削減しています。

クイックスタート

1. インストール

npm install -g @pyalwin/codemesh

インストールせずに直接実行することもできます。

npx -y @pyalwin/codemesh --help

git clone https://github.com/pyalwin/codemesh.git
cd codemesh
npm install && npm run build
npm link

インストールを確認するには、codemesh --version を実行してください。パッケージのバージョンが表示されます。

2. プロジェクトをインデックス化する

cd /your/project
codemesh index

デフォルトのインデックス作成および取得パスでは、.codemesh/ 内の SQLite データベースを1つ使用します。 埋め込みは生成せず、ベクトルデータベースも必要ありません。以前の実行で作成されたベクトル関連の成果物はそのまま残りますが、このパスでは使用されません。

Indexed 656 files
  Symbols found:  16733
  Edges created:  33266
  Duration:       10009ms
  PageRank:       13843 nodes scored

3. モードを選択する

Codemesh には、AI エージェントを統合する2つの方法があります。

{
  "mcpServers": {
    "codemesh": {
      "command": "npx",
      "args": ["-y", "@pyalwin/codemesh"],
      "env": {
        "CODEMESH_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

export CODEMESH_PROJECT_ROOT=/path/to/your/project

# Navigate one level at a time, then read a selected symbol:
codemesh explore map
codemesh explore map --node 'dir:src'
codemesh explore map --node 'file:src/server.ts'
codemesh explore source 'symbol:src/server.ts:createServer'
codemesh explore source 'symbol:src/server.ts:createServer' --mode preview
codemesh explore inspect 'symbol:src/server.ts:createServer' --depth 1 --max-symbols 4 --compact
codemesh explore hydrate --references '[{"id":"symbol:src/server.ts:createServer","bodyHash":"HASH"}]' --compact

# Other exploration commands:
codemesh explore search "request flow"
codemesh explore context Source/Core/Session.swift Source/Core/Request.swift
codemesh explore trace Session.request --depth 5
codemesh explore recall --path src/server.ts
codemesh remember --path src/server.ts --summary "Server tool registration" --session my-task

4. 使用する

エージェントは、コードを読む前に、永続的なグラフ内の経路を選択できます。

You: "Find how pydantic handles validation"

Agent calls: codemesh_map({})
       gets: immediate repository directories and files, each with an ID

Agent calls: codemesh_map({ node: "dir:pydantic" })
       gets: immediate files and subdirectories

Agent calls: codemesh_map({ node: "file:pydantic/main.py" })
       gets: top-level symbols, including BaseModel

Agent calls: codemesh_map({ node: "symbol:pydantic/main.py:BaseModel" })
       gets: methods, including model_validate

Agent calls: codemesh_source({ id: "symbol:pydantic/main.py:BaseModel.model_validate" })
       reads: only the selected symbol's source

Agent calls: codemesh_enrich({ path: "pydantic/functional_validators.py",
               summary: "Primary V2 validator API..." })
       saves: summary for next session

クライアントとの統合

Codemesh は Model Context Protocol に対応しているため、MCP 互換のクライアントであれば使用できます。以下のスニペットのいずれかを貼り付けてクライアントを再起動すると、エージェントのツールボックスに codemesh_* ツールが表示されます。

{
  "mcpServers": {
    "codemesh": {
      "command": "npx",
      "args": ["-y", "@pyalwin/codemesh"],
      "env": {
        "CODEMESH_PROJECT_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

{
  "mcpServers": {
    "codemesh": {
      "command": "npx",
      "args": ["-y", "@pyalwin/codemesh"],
      "env": {
        "CODEMESH_PROJECT_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

{
  "mcpServers": {
    "codemesh": {
      "command": "npx",
      "args": ["-y", "@pyalwin/codemesh"],
      "env": {
        "CODEMESH_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@pyalwin/codemesh"],
          "env": {
            "CODEMESH_PROJECT_ROOT": "/absolute/path/to/your/project"
          }
        }
      }
    ]
  }
}

エージェントによる書き戻し：より賢くなるグラフ

ほかのコードインテリジェンスツールは、リポジトリを一度だけインデックス化し、エージェントに読み取り専用のビューを渡します。Codemesh では、エージェントが作業しながらグラフに知識を書き込めます。要約、ワークフロー、概念間のリンクはセッションをまたいで保持され、再インデックス化しても失われません。

// Session 1 — agent reads unfamiliar code, then writes back what it learned.
codemesh_enrich({
  path: "pydantic/functional_validators.py",
  summary: "Primary V2 validator API. `@field_validator` wraps "
         + "`_decorators.FieldValidatorDecoratorInfo`; `mode='before'|'after'` "
         + "toggles pre/post-coercion execution. Extends BaseValidator.",
  sessionId: "validation-investigation-1"
})

// Session 1 — agent traces a multi-file flow, records the path.
codemesh_workflow({
  name: "pydantic field validation",
  description: "Request → BaseModel.__init__ → SchemaValidator → field_validator",
  files: [
    "pydantic/main.py",
    "pydantic/_internal/_model_construction.py",
    "pydantic/functional_validators.py"
  ]
})

// Session 2 (days later) — another agent navigates the same indexed code.
codemesh_map({ node: "file:pydantic/functional_validators.py" })
// → returns stable symbol IDs without reading their bodies.
codemesh_explore({ action: "context", path: "pydantic/functional_validators.py" })
// → includes the earlier agent's concept alongside indexed relationships.

グラフは、静的解析ツールでは推測できない情報を把握します。つまり、あるファイルが重要な理由、どのファイルが連動して変更されるか、メンテナーがある概念を何と呼んでいるかです。再インデックス化では構造レイヤー（ファイル、シンボル、インポート、呼び出し）が再構築されますが、すべてのエンリッチメントは保持されます。参照先のファイルが変更された場合にのみ、エントリーが古くなります。

MCP ツールの codemesh_enrich と codemesh_workflow を参照してください。

仕組み

                      ┌──────────────────────────────────┐
                      │         Knowledge Graph           │
                      │                                   │
                      │  ┌──────────┐ ┌───────────────┐  │
                      │  │Structural│ │   Semantic     │  │
                      │  │  (auto)  │ │   (agents)    │  │
                      │  │          │ │               │  │
                      │  │ files    │ │ summaries     │  │
                      │  │ symbols  │ │ workflows     │  │
                      │  │ imports  │ │ concepts      │  │
                      │  │ calls    │ │ enrichments   │  │
                      │  └──────────┘ └───────────────┘  │
                      │                                   │
                      │  ┌──────────┐ ┌───────────────┐  │
                      │  │   Git    │ │   Search      │  │
                      │  │  Intel   │ │               │  │
                      │  │          │ │ FTS5 (exact)  │  │
                      │  │ hotspots │ │ Trigram (fuzzy)│  │
                      │  │ co-change│ │ notes + cache │  │
                      │  │ churn    │ │ PageRank      │  │
                      │  └──────────┘ └───────────────┘  │
                      │                                   │
                      │          SQLite only              │
                      └────────────┬──────────────────────┘
                                   │
                      ┌────────────┴──────────────────────┐
                      │    MCP Server / CLI (shared core)  │
                      │                                    │
                      │  map · source · answer · explore    │
                      │  trace · recall · enrich · workflow │
                      │  status                            │
                      └────────────────────────────────────┘

構造レイヤー（自動） — Tree-sitter がコードを解析し、ファイル、シンボル（関数、クラス、メソッド）、および関係（インポート、呼び出し、継承）に分解します。インデックス化のたびに再構築されます。

セマンティックレイヤー（エージェントが構築） — エージェントはコードを扱いながら、要約やワークフローの経路を書き戻します。これらは再インデックス化後も保持され、セッションをまたいで蓄積されます。参照先のファイルが変更されると無効になります。

MCP ツール

CLI

codemesh index                          # structural + git intel + pagerank
codemesh rebuild                        # force re-index; preserves saved knowledge
codemesh status                         # graph statistics

codemesh explore map                    # repository root
codemesh explore map --node 'dir:src'   # expand one branch
codemesh explore map --node 'symbol:src/auth.ts:login' --relation calls
codemesh explore source 'symbol:src/auth.ts:login'
codemesh explore source 'symbol:src/auth.ts:login' --if-hash HASH  # unchanged reference if bytes match
codemesh explore source 'symbol:src/auth.ts:login' --force         # rehydrate exact source
codemesh explore inspect 'symbol:src/auth.ts:login' --depth 1 --compact
codemesh explore hydrate --references '[{"id":"symbol:src/auth.ts:login","bodyHash":"HASH"}]' --compact
codemesh explore answer "question"      # optional ranked context assembly
codemesh explore search "query"         # SQLite FTS5 + trigram
codemesh explore search get_default --path pydantic --scope symbols --max-bytes 4096
codemesh explore inspect 'symbol:src/auth.py:login' --direction both --max-candidates 16
codemesh explore recall --path file     # prior notes with freshness
codemesh explore context file1 file2    # multi-target context
codemesh explore trace symbol --depth 5 # follow call chains
codemesh explore impact file            # reverse dependencies
codemesh remember --path file --summary "note" --session task-id
codemesh workflow --name flow --description "flow description" --file first.ts --file second.ts
codemesh explore search "query" --compact  # 8 candidates with IDs and match reasons
codemesh explore source 'symbol:src/auth.ts:login' --mode full --compact
codemesh explore source 'symbol:src/auth.ts:login' --mode auto --compact
rg -n 'login' src | codemesh adapt search  # reversible fold when smaller
cat src/auth.ts | codemesh adapt read --path src/auth.ts --intent navigate

--compact は map、search、source、recall、inspect、hydrate で利用できます。CLI JSON から 繰り返されるメタデータを削除します。source には、要求された正確なコードと コンテンツハッシュが引き続き含まれます。ナビゲーションマップ、検索、inspect、hydrate は、整形せずに 上限付きの JSON を出力します。コンパクト形式でも、正確なソースコードと鮮度ハッシュは保持されます。 hydrate では、ディスクに保存した JSON 配列を指定する --references-file PATH も受け付けます。 上限付きのレスポンスでは、最終的な JSON が要求された予算内に収まるよう、追加のプロジェクトルートのラッパーを省略します。 その他のコマンドでは、従来のレスポンス形式が維持されます。

引き継ぎ時には、新しいソース取得結果からシンボルの正確な ID と bodyHash を保存してください。 codemesh_hydrate は、全コードを返す前に、そのハッシュを現在のソースと照合します。 保存した hash が fold または preview に由来する場合は、その mode を含めてください。そのハッシュが 検証するのはレンダリングされたビューのみなので、シンボル全体を検証するには bodyHash も含めてください。 予算に達して省略されたブロックがある場合、inspect と hydrate はその内容を明示的に報告します。 どちらも、ソースブロックの上限はデフォルトで4、JSONレスポンスの予算は24 KiBです。inspect は、保守的に解決されたローカルの Python 関数とインポートを、最大1段階だけたどります。 呼び出し元の候補も調べるには、--direction incoming または both を使用します。 --max-candidates は呼び出し元の検証数に上限を設定します（デフォルトは32、最大は128）。インデックス化された エッジは手がかりにすぎません。返される呼び出し元はそれぞれ、現在の Python バインディングと照合されます。エッジが不足している場合、 呼び出し元の検出が不完全であることが明示されます。結果が空でも、シンボルに呼び出し元がないことの証明にはなりません。動的レシーバー、 曖昧な名前、不確かなバインディングは明示的に未解決のままとなります。他の言語では、未検証のグラフ候補が提示されます。 これらは静的バインディングであり、実行時の動作を保証するものではありません。ハイドレーションは、ライブソースと照合済みのコードを返します。引き継ぎ後にいつこれを呼び出すか、 またモデルのコンテキストにどの証拠を保持するかは、クライアントが決定します。 --mode auto は明示的なナビゲーション表示です。120 行以下かつ 12KiB 以下のシンボルは全体を返し、それより大きいシンボルは省略範囲とメンバーをマップするヒントを含む、範囲を限定したプレビューを返します。明示的に --mode full を指定すると、常にソース全体を正確に返します。 検索では、完全一致する識別子と完全一致する修飾名／末尾名が最優先され、次にクエリ語の網羅率と字句的な関連度で順位付けされます。人気度は同順位の場合にのみ使用されます。 オプトインの構造ヒントには、--exact-tie-break path-depth を指定すると、同順位の完全一致する名前／末尾名について、人気度よりも浅いパスが優先されます。MCP では、codemesh_explore に同じ exactTieBreak オプションが用意されています。明示的な ID とパスフィルターでは、引き続きより深い実装を選択できます。深さによって、どの実装が正規であるかが決まるわけではありません。デフォルトは引き続き pagerank です。 --path は SQLite の結果上限が適用される前に、候補をファイルまたはディレクトリに絞り込みます。src は src-other には一致しません。コンパクト検索にはシグネチャと範囲が含まれます。 検索とナビゲーションでは、デフォルトで 8192 バイトの JSON 予算が設定されています。--max-bytes には 512..65536 を指定できます。省略された結果は明示されます。ナビゲーションのカーソルは常に、返されなかった最初のエントリーを指します。そのエントリーだけで予算を超える場合は、--max-bytes を増やしてカーソルを再利用してください。ソースコードは引き続き source／inspect から取得します。

決定論的な Graphify のフォローアップでは、単一エージェントの設計と、焦点を絞ったコンテキストポリシーについて説明しています。コンテキストの置き換えはハーネスの役割です。MCP／CLI ツールでは、以前のクライアントメッセージを削除できません。 制御された次のイテレーションでは、簡潔な評価指示、オプションの検索順位付け、2 つの複数ファイルの引き継ぎ用フィクスチャについて説明しています。

ソース取得では、MyType.myMethod のような一意のシンボル名も使用できます。曖昧な名前の場合は、候補 ID と範囲を正確に返します。サイズからオーバーロードを推測することはありません。セッションをまたいで参照する場合は、引き続き正確な ID を推奨します。 adapt は、標準入力からネイティブのツール観測結果を読み込みます。検索の折りたたみではすべての一致を保持し、未対応の形式ではフォールバックします。読み取り時のアウトライン化には、最新のインデックス済みファイルとのバイト単位で完全一致することと、明示的なナビゲーション意図が必要です。編集時の読み取りと部分読み取りは、変更せずにそのまま通過します。--json を指定すると、適応後の観測結果のみを出力するのではなく、経路と理由を報告します。

オプション：フックとスキル

# Install the skill so Claude Code loads the workflow automatically
cp /path/to/codemesh/skills/codemesh.md /your/project/.claude/skills/

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Read",
      "hooks": [{
        "type": "command",
        "command": "/path/to/codemesh/hooks/pre-read.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Read",
      "hooks": [{
        "type": "command",
        "command": "/path/to/codemesh/hooks/post-read.sh"
      }]
    }]
  }
}

対応言語

tree-sitter の文法がある言語であれば追加できます。

グラフのデータモデル

ノード

エッジ

アーキテクチャ

codemesh/
├── src/
│   ├── index.ts              # MCP server entry (stdio transport)
│   ├── server.ts             # Tool registration (zod schemas)
│   ├── graph/
│   │   ├── types.ts          # Node/edge type definitions
│   │   ├── storage.ts        # StorageBackend interface (swappable)
│   │   └── sqlite.ts         # SQLite + FTS5 implementation
│   ├── indexer/
│   │   ├── indexer.ts        # File walking, hashing, incremental indexing
│   │   ├── parser.ts         # Tree-sitter AST extraction
│   │   └── languages.ts      # Language registry (ext → grammar)
│   ├── tools/                # 6 MCP tool handlers
│   └── cli.ts                # CLI entry point
├── skills/codemesh.md        # Agent education skill
├── hooks/                    # Pre/post read hooks
└── eval/                     # Eval framework (5 tasks, 3 models)

ストレージはバックエンドに依存しません。StorageBackend インターフェースがすべての永続化を抽象化します。v1 では、依存関係なしでローカル動作する SQLite と FTS5 を使用します。このインターフェースにより、Memgraph、Neo4j、その他のグラフデータベースへの切り替えが可能です。

評価フレームワーク

LLM による判定スコアリングを備えた、再現可能な評価ハーネスです。

# Setup
npm install -g @pyalwin/codemesh
git clone --depth 1 https://github.com/Alamofire/Alamofire.git /tmp/alamofire
# ... clone other repos ...

# Index
CODEMESH_PROJECT_ROOT=/tmp/alamofire codemesh index

# Run benchmarks
python3 eval/head_to_head.py --model sonnet alamofire excalidraw vscode swift-compiler

詳しい方法論と結果については、docs/benchmark-results.md をご覧ください。初期の Pydantic 評価は docs/experiments/ にアーカイブされています。

SQLite 専用 CLI には、ピン留めされた Pydantic のチェックアウトを使った別個の vNext コントラクトおよびエージェントワークフロー評価があります。その正確性チェックとモデルのコスト／品質の比較は、過去のベンチマークとは分けて報告されています。 vNext Pydantic の結果には、最初の完全なペア実行が記録されています。

既存ツールとの比較

開発

bun install          # Install dependencies
bun run build        # Compile TypeScript
bun run test         # Run 102 tests
bun run dev          # Watch mode
bun run lint         # Type check

コントリビューション

コントリビューションを歓迎します。改善できる領域は次のとおりです。

• 対応言語の拡充 — tree-sitter の文法と、言語固有の抽出器を追加する
• AST 差分による無効化 — ファイル単位ではなく、関数単位で古さを検出する
• グラフバックエンド — StorageBackend 用の Memgraph／Neo4j アダプター
• セマンティック検索 — FTS5 と併用する埋め込み列
• エージェントの採用 — エージェントが自然にグラフツールを優先するための、よりよいパターン

ライセンス

MIT