Tesserae v0.3.0 — 散文からコードへのリンク、ポリグロットなコードグラフ、ライブ同期

<!-- translations:start -->

English · 한국어 · 中文 · Русский · Español · Français · Deutsch

<!-- translations:end -->

リリース日 2026-05-24 · PyPI · GitHub release · pip install --upgrade tesserae==0.3.0

Tesserae 0.3.0 は、散文(prose)上の意思決定と、それを実装するコードシンボルとの間のループを閉じます。しかも v0.2.0 が Python 限定だった基盤に対し、本リリースでは 21 言語に対応します。本リリースは破壊的変更のない加算的な 3 つの機能を提供します。すなわち、セッション由来の知見(SessionInsight、Decision、Hypothesis、Todo、Question、Takeaway)から該当するコードノードへ型付きリンクを生成する discusses エッジパス、colbymchenry/codegraph の tree-sitter ベースの SQLite インデックスを Tesserae の型付き ResearchGraph に取り込む tesserae project sync-code サブコマンド、そしてユーザーがコードを編集するたびにそのインポートを新鮮に保つ、デフォルト有効の ライブ sync-code SessionStart hook です。これらが揃うことで、Tesserae は 2026 年の landscape において、「X について何を決めたか?」という問いに対し、意思決定そのもの、それが行われたセッション、*さらに*それを実装している関数 / クラス / ルートまでを — 実際の研究用コードベースが使うポリグロットなスタックを横断して — 返すことができる唯一の PKM-AI メモリツールとなります。

目次:

1. MD0 エッジ — 散文をコードシンボルにリンクする(feature H)
2. MD0 — CodeGraph アダプタ、21 言語
3. ライブ sync-code SessionStart hook(v0.3.0 後の MD0)
4. v0.2.0 からのアップグレード
5. 戦略的コンテキスト

1. discusses エッジ — 散文をコードシンボルにリンクする(feature H)

概要

コンパイル後に走るオプトインのパスで、各セッション知見の本文をスキャンしてグラフ内に存在するコードシンボルへの言及を検出し、その知見から該当する各コードノードへ型付きの discusses エッジを生成します。ソース側のノード種別はエージェントハーネスが発行する 6 種のセッション知見(SessionInsight、Decision、Hypothesis、Todo、Question、Takeaway)で、ターゲット側は Tesserae が現時点で扱うすべてのコードノードバリアントです: CodeFunction、CodeClass、CodeMethod に加えて、v0.3.0 で新規追加された CodeInterface、CodeTrait、CodeStruct、CodeEnum、CodeEnumMember、CodeTypeAlias、CodeVariable、CodeConstant、CodeRoute、CodeComponent、CodeField、CodeNamespace、そしてフォールバックの CodeSymbol。

抽出器は精度別に 3 ティア構成になっており、ユーザーが実際に書いた識別子をエージェントハーネスが復元しつつ、偽陽性でグラフを溢れさせないようにしています。

複数ファイルで定義されているシンボルには same-name fanout(同名扇形展開) が適用されます。すなわち、セッション知見中に裸の識別子 User への言及があると、マッチした各 CodeClass ごとに(ファイル単位で)1 本の discusses エッジが生成されるため、下流の graph_ppr を当該知見でシードした際に、任意に 1 つを選ぶのではなく、もっともらしいあらゆる実装に展開されます。

新しい MCP ツール — find_code_symbol_mentions(node_id) — は、同じ抽出器をクエリ時にエージェントへ公開します。任意のノード(典型的にはセッション知見)を受け取り、その本文が言及するすべてのコードシンボルと、マッチしたティアを返します。コンパイルパスを再実行することなく「この意思決定が実際に触れているシンボルはどれか?」を尋ねたい場合に有用です。

使い方

環境変数でオプトインし、コンパイルします:

export TESSERAE_INSIGHT_SYMBOL_LINK=true
tesserae project compile

有効化すると、既知のシンボルに言及するすべてのセッション知見は 1 本以上の外向き discusses エッジを獲得します。MCP クライアントからは:

// 特定の意思決定が触れているシンボルを取得
{
  "tool": "find_code_symbol_mentions",
  "arguments": { "node_id": "decision-2026-05-22-switch-to-rrf-fusion" }
}

// → 返り値
// [
//   {"node_id": "code-function-tesserae.retrieval.hybrid.reciprocal_rank_fusion",
//    "tier": "backticked", "kind": "CodeFunction"},
//   {"node_id": "code-class-tesserae.retrieval.hybrid.HybridRetriever",
//    "tier": "dotted",     "kind": "CodeClass"}
// ]

あるいは新しいエッジを graph_ppr で辿り、ある意思決定群が触れる*コードシンボルの近傍*を引き出すこともできます:

{
  "tool": "graph_ppr",
  "arguments": {
    "seed_node_ids": [
      "decision-2026-05-22-switch-to-rrf-fusion",
      "hypothesis-2026-05-23-embedding-helps-paraphrases"
    ],
    "top_k": 20,
    "edge_type_weights": { "discusses": 3.0, "references": 1.5 }
  }
}

有効化の判断基準

• 実際にコードについて議論したセッション履歴がある場合 — 数週間にわたるプロジェクトで、Claude Code セッションが関数 / クラス / ルートを名前で参照しており、単に振る舞いを散文で記述しているだけではない場合。
• ask の回答に、それに言及する README ではなく、実装シンボル自体を引用させたい場合。
• 別ツールからグラフを消費しており(意思決定ノードからの LSP 風「go to implementation」など)、クエリ時の再抽出による推測ではなくクエリ可能なエッジが必要な場合。

プロジェクトの大半が散文ドキュメントと PDF で、Claude Code 履歴がほとんどない場合、本パスはコンパイル時間を増やすだけで有用なエッジはほとんど得られません — 無効のままにしてください。

場所

コア実装: MD0。ツール登録: tesserae/mcp_server.py。

注意点

• 裸の識別子ティアは意図的に保守的で、インデックスヒット*かつ*非ストップワードを要求します。あまりに一般的な識別子(run、get、set)はストップワードフィルタを通過するものの、多数のファイルへの fanout に埋もれます。これは既知のトレードオフであってバグではありません。
• Same-name fanout は種別(kind)ごとに行われます。User への言及が CodeClass と CodeRoute の双方にマッチした場合、両方へエッジが張られます。クラスのみが欲しい場合はクエリ時に target.kind == "CodeClass" でフィルタしてください。
• パスは sync-code(または ingest-code)の 後に走ります。コードグラフが空のまま feature H を有効にしてもリンク先がなく、エッジは 0 本になります。コンパイル順序は自動で扱われるため、手動の順序付けは不要です。
• ストップワードリストはグローバルであり、言語別ではありません。Vec を識別子として正当に使いたい Rust プロジェクトは既に動作します(Vec はストップワードに含まれません)が、プロジェクトローカルなオーバーライドは v0.4 でのフォローアップ予定です。

2. tesserae project sync-code — CodeGraph アダプタ、21 言語

概要

外部の colbymchenry/codegraph の SQLite インデックスを Tesserae の型付き ResearchGraph に取り込む新規 CLI サブコマンドです。CodeGraph は独自の MCP サーバーを備えた tree-sitter ベースのポリグロットなコードグラフ抽出器で、本アダプタはその .codegraph/codegraph.db を読み、各行を Tesserae の ResearchNode に翻訳し、.tesserae/code-graph.json に書き出します。これにより次回の tesserae project compile が拾い上げます — v0.2.0 の ingest-code の出力とまったく同じ要領ですが、はるかに広い言語ベースから生成されます。

対応言語は 1 から 21 に拡大しました: TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Scala、Dart、Svelte、Vue、Liquid、Pascal/Delphi、Lua、Luau。(v0.2.0 の tesserae project ingest-code の stdlib ast 抽出器は、Node ランタイム依存なしで Python 限定パスを使いたいユーザーのために変更なく動作し続けます。)

これらの言語にわたって tree-sitter が実際に表出する内容を表現するため、v0.3.0 では 14 個の新しい ResearchNodeType バリアントを追加しました:

…さらに 8 種の新エッジ: implements、exports、references、instantiates、overrides、decorates、type_of、returns。これらは CodeGraph のリゾルバが各言語で計算する内容に直接対応します。Tesserae の既存エッジである calls、imports、inherits_from、contains、declared_in は変更されず、引き続きポピュレートされます。

アダプタにおける最重要の設計判断は id_seed 戦略です。CodeGraph 自身の行 id は start_line を埋め込んでいるため、上に空行を 1 行追加するだけで同じシンボルに新しい id が割り当てられてしまい、id を保存する下流のエッジにとって致命的です。アダプタは CodeGraph の id を破棄し、Tesserae の id を f"{file_path}:{kind}:{qualified_name}" として再シードします。結果として、シンボルの Tesserae id は行ずれの編集を経ても変化せず、feature H の裸識別子マッチが多数のコンパイルにわたって同じノードに解決され続けます。

使い方

# 一回限り: .codegraph/codegraph.db を読み、.tesserae/code-graph.json を書き出し、
# 次回のコンパイルで拾い上げられる。
tesserae project sync-code

# プロジェクトルートとカスタムの DB / 出力パスを明示
tesserae project sync-code \
  --project /path/to/repo \
  --db /path/to/.codegraph/codegraph.db \
  --output /path/to/.tesserae/code-graph.json

# ウォッチループ — DB が変わるたびに sync-code を再実行する。
# feature 3 の SessionStart hook を入れたくないが、編集中もコードグラフを
# 新鮮に保ちたい場合に有用。
tesserae project sync-code --auto-sync

新規プロジェクトでの典型的なエンドツーエンドの流れ:

# 1. CodeGraph にリポジトリをインデックスさせる(CodeGraph 自身の CLI、初回のみ)
npx codegraph index .

# 2. それを Tesserae の型付きグラフに取り込む
tesserae project sync-code

# 3. 通常のコンパイルが code-graph.json を拾い、(有効なら)feature H が走る
export TESSERAE_INSIGHT_SYMBOL_LINK=true
tesserae project compile

# 4. これで散文とコードを横断する問いが可能になる
tesserae project ask "Which functions implement the RRF fusion decision?"

有効化の判断基準

• プロジェクトが 純粋な Python 以外、もしくは純粋な Python に Node 製のフロントエンド 1 つを加えた構成である場合。
• 既に CodeGraph を「find references」 / 「find implementations」目的の MCP サーバーとして使っており、同じインデックスから追加の抽出コストなしで Tesserae の型付きグラフを駆動させたい場合。
• 関数とクラスに加え、ルートやコンポーネント粒度(CodeRoute、CodeComponent)が欲しい場合 — これは v0.2.0 の ingest-code では生成されません。

Python のみで Node ランタイムをツールチェーンに入れたくない場合は、tesserae project ingest-code(v0.2.0)が引き続き動作し、互換性のある code-graph.json を生成します。

場所

コア実装: MD0。CLI 配線: tesserae/cli.py(897 行付近の sync-code サブパーサ)。v0.2.0 の tesserae/code_graph_extractor.py にある ingest-code サブコマンドは変更されていません。

注意点

• ポピュレート済みの .codegraph/codegraph.db(CodeGraph 自身の初回 npx codegraph index . ステップ)が必要です。DB が存在しない場合、アダプタはアクション可能なエラーメッセージとともに早期に失敗します。
• CodeGraph のリゾルバは 21 言語を横断する best-effort なものです。病的なジェネリクスやマクロ多用のコードでは未解決の参照が時折発生することを想定してください。アダプタは CodeGraph が出力したものを記録するのみで、再解決は試みません。
• 一部のノード種別(CodeParameter、CodeField)は、CodeGraph の言語別抽出器がそれらを表出した場合にのみ発行されます — 言語によってカバレッジは異なります。フォールバックの CodeSymbol 種別は、まだ型付けしていない tree-sitter 由来のあらゆるものを拾うため、何かが暗黙裏に捨てられることはありません。
• アトミック書き込みは一時ファイルに PID + ランダムサフィックスを用いており(共有の .tmp ではありません)、同時実行される 2 つの sync-code が衝突しないようになっています — これは batch manifest writer に最近入った修正と同じ方針です。

3. ライブ sync-code SessionStart hook(v0.3.0 後の main)

概要

Tesserae plugin 内の小さな SessionStart hook で、「更新され続けるコードグラフ」のループを閉じます。CodeGraph の MCP サーバー自体は既にファイルシステムを自動監視しており、編集に応じて .codegraph/codegraph.db を新鮮に保ちます — しかし Tesserae の .tesserae/code-graph.json は手動で sync-code を実行したときにしか更新されませんでした。本 hook は Claude Code がセッションを開くたびに tesserae project sync-code --project <root> をバックグラウンド起動します。ただし SQLite DB が派生 JSON より新しい場合に限ります。

デフォルト有効。プロジェクト単位のオプトアウトは .claude/tesserae.local.md のフロントマターで行います:

---
hooks:
  sync_code_on_start: false
---

hook は以下のいずれかに該当する場合に静かにスキップするため、CodeGraph を使わないプロジェクトに余計なノイズを足すことはありません:

• プロジェクトが CodeGraph を使っていない(.codegraph/codegraph.db がない)。
• .tesserae/code-graph.json が DB と同等またはそれより新しい。
• tesserae バイナリが PATH 上にない。
• 同じプロジェクトルートに対して別の sync-code が既に走っている(pgrep ベースの再入ガード、0a3d35f で入った SessionEnd compile guard と同じ方式)。
• ユーザーが sync_code_on_start: false でオプトアウトしている。

実際に発火する場合、セッションヘッダに 1 行表示されます:

  ⟳ syncing code-graph from CodeGraph (background)

…そして実際の sync-code 起動はデタッチ(setsid → nohup → 素の & フォールバック)で走り、出力は .tesserae/.session-start-hook.log に取り込まれます。これにより Claude セッションのトランスクリプトに漏れることなく何が起きたかを確認できます。

本 hook は v0.3.0 後に main に入り(PR #11、コミット 395e9fb)、次のコンパイル / プラグインマーケットプレイス公開で配布されます。v0.3.0 の PyPI 自体はこれを同梱しません — hook は tesserae Python パッケージではなくプラグイン側に存在するためです。

使い方

Claude Code マーケットプレイス経由で Tesserae plugin をインストール済みなら、既に入っています — hook はデフォルトで有効です。実行されたか確認するには:

tail -n 20 .tesserae/.session-start-hook.log

単一プロジェクトで無効化したい場合(例: ingest-code を好む Python 専用リポジトリ):

mkdir -p .claude
cat > .claude/tesserae.local.md <<'EOF'
---
hooks:
  sync_code_on_start: false
---

このプロジェクトは CodeGraph アダプタの代わりに `tesserae project ingest-code`
(Python AST)を使っているため、ライブ sync-code hook を無効化しています。
EOF

新しいセッションを待たずに一回限りの sync を強制したい場合は、tesserae project sync-code を直接実行するだけです — hook と手動コマンドは同じ pgrep ガードを共有するため、二重実行されることはありません。

有効化の判断基準

• 各編集バッチ後に sync-code を再実行することを忘れずに済む、「更新され続ける」性質が欲しい場合。
• エディタセッションが短く頻繁である場合(セッションを開く → 質問する → 閉じる) — 各新規セッションが最新のコードグラフを参照することを hook が保証します。
• 既に CodeGraph の MCP サーバーをファイル監視付きで動かしている場合 — hook はその新鮮さを Tesserae に伝播するだけです。

タイトな内側ループの最中で、セッションごとに何らかのバックグラウンド処理を生成したくない場合や、プロジェクトが CodeGraph を全く使わない場合(その場合 hook は静かに no-op になりますが、明示的なオプトアウトの方がクリーンです)はオフのままにしてください。

場所

• Hook エントリーポイント: MD0
• 設定パーサ: MD0 — read_plugin_setting テーブルに sync_code_on_start=true のデフォルトが追加されました。
• 再入ガード: SessionEnd compile guard(hooks/session-end.sh)と同じ pgrep -f "tesserae project sync-code.*${project_root}" パターン。

注意点

• hook は SessionStart でのみ発火し、ファイル保存ごとには発火しません。新しい Claude セッションを開かずに編集中も継続的に sync-code を走らせたい場合は、別ターミナルで feature 2 の tesserae project sync-code --auto-sync を使ってください。
• mtime 比較は BSD stat -f %m(macOS)→ GNU stat -c %Y(Linux)→ [[ A -nt B ]] フォールバックの順で行います。低解像度の mtime をもつ風変わりなファイルシステムでは、CodeGraph インデックスから 1 秒未満で走った sync をたまにスキップすることがあります — 次のセッションで拾われます。
• バックグラウンドのスポーンは利用可能なら setsid、次に nohup、最後に素の & を使います。これらのいずれもプロセスをデタッチできない極端にロックダウンされたシェルでは、sync は走るもののセッション起動を数秒ブロックする可能性があります。その場合はターミナルフレンドリーなシェルを開くか、sync_code_on_start: false を設定してください。

v0.2.0 からのアップグレード

pip install --upgrade tesserae==0.3.0

アップグレードはこれだけです — v0.3.0 は加算的で破壊的変更なしです。デフォルトの tesserae project compile の挙動は変わりません。新規部分はオプトインかつ発見可能です。

新オプトインパス用の環境変数(feature 1):

# コンパイル後に走る、散文→コードの discusses エッジパス(feature H)を有効化
export TESSERAE_INSIGHT_SYMBOL_LINK=true

指の記憶に加えるべき新 CLI サブコマンド(feature 2):

tesserae project sync-code             # 一回限りの CodeGraph → Tesserae インポート
tesserae project sync-code --auto-sync # ウォッチループ

v0.2.0 の tesserae project ingest-code サブコマンドは変更なく動作します — プロジェクトが Python 以外も含むなら sync-code を、Node ランタイム依存を入れたくないなら ingest-code を選んでください。

エージェントが利用できるようになった新 MCP ツール(feature 1):

• find_code_symbol_mentions(node_id) — 任意のノード本文に対するクエリ時のシンボル抽出。

新規プラグイン設定(feature 3、v0.3.0 後の main):

# .claude/tesserae.local.md
---
hooks:
  sync_code_on_start: true   # デフォルト; false に設定するとライブ sync hook を無効化
---

その他 — graph_ppr、ハイブリッドな search_nodes、embedding_status、list_communities、fresh_insights、コミュニティサマリ、decay スコアリング、supersedes、スキーマドリフト、スラッシュコマンド、wiki / Obsidian プロジェクション — はすべて v0.2.0 から変更ありません。

戦略的コンテキスト

Tesserae v0.2.0 では、型付きコードグラフノードと散文側のプリミティブ(decay、supersedes、コミュニティサマリ)を敷設しました。v0.3.0 は、その両半分がつながるリリースです。feature H は意思決定や仮説からそれらが触れるシンボルへ型付きの discusses エッジを生成し、CodeGraph アダプタはそうしたシンボルが、実際の研究用コードベースが使うポリグロットなスタック — TypeScript、Rust、Go、Swift、そして他 17 言語 — をカバーするようにします。Python だけではなく。

このマイルストーン前に我々が survey した wave-1 PKM-AI landscape には、これを行う他のツールはありません。Cursor Memories はプロジェクト単位のテキスト袋にすぎず、グラフも型付きエッジもありません。Claude CLAUDE.md はフラットな markdown ファイル 1 つです。Cline memory-bank は markdown ファイルのディレクトリで、型付き抽出はありません。Aider CONVENTIONS.md は単一のプロンプトプリフィックスファイルです。これらのいずれも、散文上の意思決定をそれを実装する関数やクラスに結びつけませんし、Decision と CodeRoute が異なる種類の存在であることを知りません。v0.3.0 の、21 言語の型付きコードノードを横断する discusses エッジが楔(wedge)です — そしてライブ SessionStart hook は、その楔をユーザーが覚えておくべきワークフローではなく*環境のプロパティ*のように感じさせるためのものです。

より広い GraphRAG 空間における最も近いピア — Microsoft GraphRAG — は型付きエンティティとコミュニティサマリ(Tesserae v0.2.0 がミラーするもの)を持ちますが、コードグラフ層は一切ありません。それは corpus-RAG システムであり、プロジェクトメモリコンパイラではありません。HippoRAG 2 の PPR プリミティブ(Tesserae v0.2.0)と Mem0 のメモリ操作(Tesserae v0.2.0 の supersedes)が、散文側の state of the art を補完します。v0.3.0 はそれらのいずれも触れていない次元を追加します: エージェント自身の知見から、その知見が対象とするコードを表す型付きノードへの、実際のコードベースが書かれている言語での型付きエッジ。

関連項目:

• v0.2.0 リリースノート — 型付きリトリーバル、コードグラフ(Python)、オントロジー進化
• アーキテクチャ概要 — モジュールマップとパイプライン
• Feature map — ソースリンク付きの完全な機能ステータス表
• Sessions integration — feature H がリンク元とするセッション知見のソースノード
• MCP integration — 完全な MCP ツール一覧(新規 find_code_symbol_mentions ツールは次回のドキュメントパスでここに着地します)