29.5 KB · updated 2026-07-06 · md

v0.2.0.ja.md

docs/i18n/release-notes/v0.2.0.ja.md

Tesserae v0.2.0 — 型付き検索、コードグラフ、オントロジー進化

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

リリース日 2026-05-21 · PyPI · GitHub release · pip install --upgrade tesserae

Tesserae 0.2.0 は v0.1.0 系列の上に積み上げる最初のフィーチャーリリースであり、破壊的変更なしで 6 つの追加機能 を提供します。本リリースでは、Tesserae の検索面を「型付きグラフ上の BM25」から HippoRAG-2 スタイルのハイブリッドリトリーバー（Personalized PageRank（パーソナライズドPageRank）によるシード拡張付き） へと押し上げ、散文的なインサイトをソースシンボルへと結びつける code-as-graph の土台を敷き、さらに 2 つのオントロジー進化パス（コミュニティサマリーとメモリ減衰）と、スキーマドリフトレポートを追加しています。これらの機能は、ユーザーワークフロー上の 3 つのポイントに対応します。すなわち、クエリ時 の再現率向上（graph_ppr、ハイブリッド search_nodes）、コンパイル時 のリッチなノード生成（ingest-code、コミュニティサマリー、decay/supersedes）、そしてオントロジー自体の イテレーションループ の高速化（schema-drift）です。

MD0 — 型付きグラフ上の Personalized PageRank
ハイブリッド MD0 — BM25 + lexical + embedding を RRF で融合
MD0 — Python AST から型付きコードグラフへ
コミュニティサマリー — Louvain + LLM（オプトイン）
減衰スコアリング + MD0 + MD1
MD0 — EDC による enum 提案
v0.1.0 からのアップグレード
戦略的コンテキスト

1. `graph_ppr` — 型付きグラフ上の Personalized PageRank

これは何か

ひとつ以上のノード ID をシードとして Personalized PageRank（PPR） を実行し、定常分布の質量によってランク付けされた top-k 個の関連ノードを返す、新しい MCP ツールです。このランダムウォークは 型を意識します。エッジはその関係種別に応じて重み付けされ、デフォルトプロファイルでは、Tesserae グラフ内で最も「実質的な」シグナルを伝える 4 つのエッジタイプ — derived_from_session、discussed_in、references、supersedes — をアップウェイトします。これは HippoRAG 2 が用いるのと同じマルチホップ・シード拡張プリミティブですが、パッセージレベルの共起グラフではなく Tesserae の型付きエッジに適応させたものです。

具体的には、graph_ppr は 「このノードの近傍は、私が本当に気にしている関係で重み付けすると何か？」 という問いに、素朴な BFS や BM25 では到達できない形で答えます。たとえば Decision をシードにすると、それを生み出したセッション、それが答えた質問、それが置き換えた文書、そしてそれらの文書が論じたコンセプト — たとえそれらのノードに同じキーワードが含まれていなくても — を引き寄せます。

使い方

このツールは Tesserae MCP サーバーの起動時に自動的に登録されます。任意の MCP クライアントから次のように呼び出せます。

// 単一ノードをシードに、デフォルト α=0.15、上位 10 件
{
  "tool": "graph_ppr",
  "arguments": {
    "seed_node_id": "decision-2026-05-12-switch-to-hybrid-retrieval",
    "top_k": 10
  }
}

// 複数ノード（「コンセプトクラスター」）をシードに、カスタム α + エッジ重み
{
  "tool": "graph_ppr",
  "arguments": {
    "seed_node_ids": ["concept-rrf", "concept-bm25", "concept-embedding-fusion"],
    "top_k": 25,
    "alpha": 0.2,
    "edge_type_weights": {
      "derived_from_session": 3.0,
      "discussed_in": 2.0,
      "references": 1.5,
      "supersedes": 1.5
    }
  }
}

ツールは定常質量で並んだ {node_id, score, kind, title} レコードの配列を返します。Claude Code セッションからは、エージェントに「graph_ppr を <node> をシードに top-k 15 で使って」と頼むだけで、using-tesserae スキルが呼び出しをルーティングします。

いつ使うか

graph_ppr を使うべき場面:

明確に同定された 1 つのノード（決定、論文、セッション所見）があり、そのキーワード一致兄弟ではなく グラフ距離における近傍 が必要なとき。
マルチホップな再現率がほしいとき — 例: 「このコンセプトから 2〜3 ホップ離れたすべてを、セッション由来の所見にバイアスをかけて取得したい」。
素朴な search_nodes が正しいノードを返すものの、その references リンクされたコンテキストが狭すぎるとき。

フレーズから始まる自由テキストクエリにはハイブリッド search_nodes（機能 2）を、既知のノードのテキスト的コンテキスト取得には node_context を選んでください。

実装場所

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

注意点

デフォルトの α=0.15（再起動確率）と 50 回反復の上限は、プロジェクトメモリで典型的な 5k〜50k ノード規模のグラフ向けにチューニングされています。非常に大きなグラフ（>250k ノード）では、より低い α と次数を考慮した初期化が必要かもしれません。これはフォローアップ事項です。
エッジ重みは対称的に適用されます。非対称プロファイル（たとえば references とその逆向きに異なる重みを与える）はまだ公開されていません。
実装は純 Python で、新しいランタイム依存はありません。1 セッション中に graph_ppr を数千回呼び出すホットループがあるなら、呼び出し間で列確率行列をキャッシュすることを検討してください。

2. ハイブリッド `search_nodes` — BM25 + lexical + embedding を RRF で融合

これは何か

既存の search_nodes MCP ツールに mode パラメータが追加され、その下に融合型リトリーバーが導入されました。新しいデフォルトである mode="hybrid" は 3 種類のリトリーバーを並列実行します — BM25（v0.1.0 のベースライン）、lexical（トークン重複/部分文字列）、embedding（意味的類似度） — そしてこれらを Reciprocal Rank Fusion（RRF） で融合します（RRF(d) = Σ 1/(k + rank_i(d))、k=60 は Cormack et al. 2009 の定数）。これは Microsoft GraphRAG のローカル検索や LightRAG のハイブリッドモードが用いるのと同じ融合レシピです。

mode パラメータが受け付ける値:

モード	使用するリトリーバー
`hybrid` (デフォルト)	BM25 + lexical + embedding を RRF で融合
`lexical`	lexical のみ
`bm25`	BM25 のみ
`embedding`	embedding のみ
`legacy`	v0.1.0 時点のランキングをビット単位で完全に保持

embedding バックエンドは次の順序で自動検出されます。sentence-transformers がインポート可能であれば、sentence-transformers/all-MiniLM-L6-v2（384 次元、約 80MB、MIT ライセンス、初回ダウンロード後はネットワーク呼び出しなし）をロードします。利用できない場合は、決定論的な hash-bucket 射影にフォールバックします — 使用可能で依存なし、再現可能ですが、意味的再現率は弱めです。

新しい姉妹 MCP ツール embedding_status は、現在アクティブなバックエンドを報告するため、あなたのハイブリッドスコアが実 embedding の恩恵を受けているか、それとも hash-bucket フォールバックで動いているかを確認できます。

使い方

// 新デフォルト — 融合検索、上位 10 件を返す
{
  "tool": "search_nodes",
  "arguments": { "query": "RRF fusion constant choice", "top_k": 10 }
}

// アブレーションのため単一リトリーバーを強制
{ "tool": "search_nodes", "arguments": { "query": "RRF fusion", "mode": "bm25" } }

// v0.1.0 の挙動にビット単位で巻き戻す
{ "tool": "search_nodes", "arguments": { "query": "RRF fusion", "mode": "legacy" } }

// アクティブな embedding バックエンドを確認
{ "tool": "embedding_status", "arguments": {} }

hash-bucket フォールバックではなく本物の sentence-transformers バックエンドを得るには次のようにします。

pip install 'sentence-transformers>=2.7'
# 初回呼び出しで MiniLM の重み（約 80MB）が HF キャッシュにダウンロードされます。以降はオフラインで動作します。

どのモードをいつ使うか

hybrid をすべてのデフォルトに。RRF はあるリトリーバーがゴミを返しても頑健です。ランクの逆数による減衰が、単一リトリーバーの寄与に上限を設けるためです。
bm25 はクエリが本質的にタグや構造的スラグ（concept-rrf、decision-2026-05-12-…）であるとき。完全一致が支配的になり、embedding はノイズになります。
embedding はクエリが言い換えや疑問文で、一致するノードが大きく異なる語彙を使っているとき。
legacy は v0.1.0 ベースラインに対するアブレーションのため、あるいは単一の回帰が見つかった場合の脱出ハッチとして。

実装場所

コア実装: MD0。

注意点

hash-bucket フォールバックは再現可能ですが、言い換えに対する意味的再現率には限界があります — embedding_status でその選択が可視化されます。
現在の RRF 定数は 60 に固定されています。呼び出しごとに変更可能にするのは小さなフォローアップ事項であり、他の値を試したい場合に対応できます。
embedding キャッシュはプロセスごとです。永続化された embedding ストア（Lance/SQLite-vec）は将来 v0.3 の候補です。

3. `tesserae project ingest-code` — Python AST から型付きコードグラフへ

これは何か

Python リポジトリを標準ライブラリの ast モジュールで走査し、5 種類の型付きノード と 5 種類のエッジ を生み出す新しい CLI サブコマンドです。

ノード	エッジ
`CODE_FILE`、`CODE_MODULE`、`CODE_CLASS`、`CODE_FUNCTION`、`CODE_METHOD`	`contains`、`calls`、`imports`、`inherits_from`、`declared_in`

結果は .tesserae/code-graph.json に永続化され、次回の tesserae project compile で取り込まれます。これによりコードシンボルはファーストクラスのグラフノードとなり、散文からリンクし、search_nodes で検索し、graph_ppr で展開し、コンセプトや論文と並べて可視化できるようになります。これは 決定をそれを実装したシンボルへ結びつける ための土台です — 2026 年現在、他のどの PKM-AI ツールも埋めていないくさび（ウェッジ）です。

使い方

# アクティベート済みの Tesserae プロジェクトから
tesserae project ingest-code

# 任意のルートに対して
tesserae project ingest-code --root ./my-package

# 通常の compile が新しい code-graph.json を拾います
tesserae project compile

次回のコンパイル後、コードノードが検索可能になります。

tesserae ask "Where is the RRF fusion implemented?"

…そしてエージェントは、散文の Decision ノードから、それを実装する CODE_FUNCTION まで references / declared_in エッジを辿って歩いていけます。

いつ使うか

決定や所見を、それを言及する README ではなく、実際のシンボルにリンクさせたい とき。
別途コード検索インデックスをセットアップせずに コードを意識した検索 がしたいとき — 同じ search_nodes + graph_ppr ツールで散文とコードの両方をカバーできるようになります。
Understand-Anything 統合を使っているが、サイドカー JSON ではなくメイン Tesserae グラフ内に存在する より軽量で依存のない コードグラフがほしいとき。

実装場所

コア実装: MD0。

注意点

v0.2.0 では Python のみ です。抽出器は将来言語ごとのウォーカーを追加できるように構造化されています。TypeScript / Rust / Go は v0.3 のロードマップにあります。
calls エッジは 同一モジュールスコープ内の名前解決 によって解決されます。モジュール間の呼び出し解決はインポートエイリアスを使いますが、完全な型推論は行いません。多重定義された名前では中程度の偽陽性率を想定してください — 検索用途には十分ですが、リファクタリング用途には不十分です。
デコレータは被装飾ノードの属性として記録されますが、（今のところ）独自のエッジ種別は持ちません。

4. コミュニティサマリー — Louvain + LLM（オプトイン）

これは何か

型付きグラフに対して Louvain コミュニティ検出 を実行し、その後サイズ 4 以上の各コミュニティについて LLM に 1 段落のサマリーを生成させる、オプトインのコンパイル後パス です。各サマリーは COMMUNITY_SUMMARY ノード として実体化され、summarizes エッジでメンバーにリンクされ、メンバー ID リストの SHA をキーにキャッシュされるため、再コンパイル時にはメンバーシップが実際に変わったコミュニティのみ再サマリー化されます。これは Microsoft GraphRAG がクエリ時に「このクラスターは何についてのものか？」を浮かび上がらせるのに用いるパターンと同じです。

新しい MCP ツール list_communities(min_size, limit) は、メンバー数でランク付けされたコミュニティサマリーノードを返すので、グラフ全体をロードせずにマクロ構造をブラウズできます。

使い方

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

export TESSERAE_COMMUNITY_SUMMARIES=true
tesserae project compile

その後、得られたサマリーをクエリします。

{ "tool": "list_communities", "arguments": { "min_size": 5, "limit": 20 } }

あるいは node_context を介してコミュニティサマリーノードの summarizes エッジを辿り、メンバーへ戻ることもできます。

いつ有効にするか

中〜大規模のグラフ（経験則として 500 ノード以上）があり、クラスターレベルの目次 がほしいとき。
LLM が書いたクラスターラベルを、静的サイトのグラフビューのカラーグループに付加させたいとき。
定期的なダイジェスト（週次 / 月次）を作成しており、メンバーシップが実際に変化したときだけ更新される「マクロ構造」セクションがほしいとき。

グラフが小規模（単一プロジェクトの README と数本のドキュメント）であれば、既存の構造的な Synthesis ノードで十分です — コミュニティサマリーはシグナルではなくノイズを足してしまいます。

実装場所

コア実装: MD0。

注意点

デフォルトでは無効です — Louvain + LLM サマリー化は実行時間を加算しますし、コミュニティの多いグラフでは LLM コストも無視できません。キャッシュにより再コンパイル間でこれを償却します。
Louvain のシードによってコミュニティのメンバーシップは非決定的になります。本パスはプロジェクト内での再現性のためにシードを固定しますが、プロジェクト間でのコミュニティ ID の比較は意味を持ちません。
サマリープロンプトは汎用的です。ドメインごとのプロンプトオーバーライドは予定されているフォローアップ事項です。

5. 減衰スコアリング + `supersedes` + `fresh_insights`

これは何か

2 つの相補的なプリミティブで、いずれも A-MEM の Ebbinghaus 減衰メモリモデルに着想を得ています。

減衰スコアリング は、すべてのセッション所見ノード（Insight / Decision / Question / TODO / Hypothesis / Takeaway）に古典的な忘却曲線を用いて連続値 decay_score ∈ (0, 1] を割り当てます。

decay_score = exp(-ln(2) · age_days / half_life)

デフォルトの半減期は 14 日 で、access_count のバンプ（ask や fresh_insights でノードが浮上するたびに加算）により減衰がさらに遅くなります。構造的決定のタイムスタンプは親セッションから導出されるため、後付けされた所見にも妥当な年齢が付きます。

supersedes パス は オプトイン のコンパイル後ステップで、タイトル + 本文シングルに対する Jaccard 類似度 で近似重複セッション所見を見つけ、その後 LLM に「新しい方が本当に古い方を置き換えるか」を判定させます。確認されたペアには supersedes エッジが張られ、古いノードの実効的な decay_score は抑制されます。

新しい MCP ツール fresh_insights(limit, kind) は、現在の decay_score で上位の所見を返します。置き換えられたノードは除外 されます。これは「過去のセッションから何をエージェントは優先すべきか？」という正準クエリです。

使い方

減衰スコアリングはすべてのコンパイルで自動的に走ります。supersedes パスを有効にするには:

export TESSERAE_SUPERSEDE_PASS=true
tesserae project compile

その後、最も新鮮で置き換えられていない所見をクエリします。

{
  "tool": "fresh_insights",
  "arguments": { "limit": 15, "kind": "Decision" }
}

あるいは kind を省略して、すべてのセッション所見種別を混在させたフィードを取得します。

supersedes パスをいつ有効にするか

週次でセッションが蓄積しており、Decision / Hypothesis クエリが矛盾する古いエントリを返し始めたとき。
エージェントの using-tesserae の再現フローを、「X について我々がかつて考えたすべて」ではなく「X についての現時点の考え」へバイアスしたいとき。
コストが許容できるとき: コンパイルごとに Jaccard パスを 1 回（安価）と、Jaccard しきい値を超えた候補ペアに対する N 回の LLM 判定呼び出し（コンテンツハッシュでキャッシュ）を支払います。

セッションが数週間分しかない場合は、減衰だけで通常は十分です — supersedes エッジは、より古く、より密なグラフ向けの最適化です。

実装場所

減衰スコアリング: MD0
supersedes パス: MD0

注意点

14 日の半減期はアクティブな研究プロジェクトに対する妥当なデフォルトです。長期アーカイブグラフでは 60〜90 日が望ましいかもしれません。種別ごとの半減期テーブルは v0.3 で予定されている機能です。
Jaccard 候補生成はシングルサイズ 5 に固定されています。非常に短い所見（一文の Takeaway）はクラスター化されにくい場合があります。
supersedes の LLM 判定は設計上保守的です — 偽陰性（見逃された重複）は偽陽性（誤った supersedes エッジ）よりも多くなります。

6. `tesserae project schema-drift` — EDC による enum 提案

これは何か

オントロジーがコーパスとともに進化する ことを助ける新しい CLI サブコマンドです。EDC パターン（Extract-Define-Canonicalize、EMNLP'24）を実装しており、高ボリュームのノード種別ごとに、タイトル + 本文シングルでメンバーを Jaccard クラスタリング し、その後 LLM に PascalCase のサブタイプを提案 させます。各クラスターについて簡単な根拠と 3 件の代表メンバープレビューが付きます。出力は .tesserae/schema-drift.md に書き出され、ontology/ 配下のオントロジーファイルへコピー&ペースト可能な enum 追加項目のチェックリストとなります。

LLM 提案は アトミックに（一時ファイルに書いてからリネーム）キャッシュされ、クラスターのメンバー ID の SHA をキーとします。そのためパスの再実行は安価で、コーパスが変化していないかぎり同じ提案に収束します。

使い方

tesserae project schema-drift
# → .tesserae/schema-drift.md を書き出す

その後レポートを開き、提案された enum を確認（各ブロックはコピー&ペースト可能な Python リテラルです）し、採用したものを ontology/ 配下の該当ファイルへ貼り付けます。次回の tesserae project compile は更新後のスキーマで検証を行います。

いつ使うか

大量の新規ドキュメント / セッションのバッチ取り込み後、新しいノード種別値をファーストクラス enum に昇格させる前に。
長期運用プロジェクトで定期的に（月次）実行し、オントロジードリフトを浮かび上がらせる — レポートは高速で読み取り専用です。
ハンドオフアーティファクトとして: マークダウンは自己完結しているので、フル Tesserae CLI を整えなくてもレビュアー（あるいは別エージェント）に渡せます。

実装場所

コア実装: MD0。

注意点

提案はあくまで示唆です — どのクラスターが実際の enum 値になるかは、人間（または下流のエージェント）が決めます。本パスは意図的に ontology/ を自動的に書き換えません。
Jaccard クラスタリングは supersedes パスと同じシングルサイズの前提を共有します。非常に短いメンバーはクラスタリングがあまり鋭くならない場合があります。
本パスは高ボリュームの種別に焦点を当てます。希少な種別（メンバー数 3 以下）は、投機的な enum を避けるためにスキップされます。

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

pip install --upgrade tesserae

アップグレードはこれで全部です — v0.2.0 は 追加的で破壊的変更はありません。知っておくべきオプションのつまみがいくつかあります。

オプトインパス向けの 環境変数:

# コンパイル後のコミュニティサマリーパスを有効化（機能 4）
export TESSERAE_COMMUNITY_SUMMARIES=true

# supersedes の近似重複パスを有効化（機能 5）
export TESSERAE_SUPERSEDE_PASS=true

知っておくべき唯一の MCP 表面の変更: search_nodes のデフォルトが mode="hybrid" になりました。v0.1.0 の厳密なランキングに依存した自動化があるなら、mode="legacy" を渡してください — レガシーパスはビット単位で保持されています。

実 embedding バックエンド向けの 新しい、オプションの Python 依存:

pip install 'sentence-transformers>=2.7'

これをスキップしても search_nodes mode="hybrid" は動きます（hash-bucket フォールバック）。embedding_status は minilm-l6-v2 ではなく hash-bucket を報告するため、選択は観測可能です。

筋肉記憶に加えるべき 新しい CLI サブコマンド:

tesserae project ingest-code      # コードノードを生成（機能 3）
tesserae project schema-drift     # オントロジー enum を提案（機能 6）

エージェントが新たに利用できる 新しい MCP ツール:

graph_ppr（機能 1）
embedding_status（機能 2）
list_communities（機能 4）
fresh_insights（機能 5）

それ以外 — スラッシュコマンド、フック、ask、wiki / Obsidian プロジェクション — はすべて変更ありません。

戦略的コンテキスト

v0.2.0 は Tesserae を 2026 年の GraphRAG / エージェントメモリの最先端 と構造的に足並みを揃えるものです。

ハイブリッド検索（RRF による BM25 + lexical + embedding） は、Microsoft GraphRAG のローカル検索や LightRAG のハイブリッドモードが用いるのと同じ融合レシピです。
Personalized PageRank によるシード拡張 は HippoRAG 2 の中核にあるマルチホップ・プリミティブで、ここではパッセージ共起ではなく型付きエッジに適応されています。
コミュニティサマリー は Microsoft GraphRAG のクラスターサマリー層を映したものです — 「このコーパスはおおまかに何についてのものか？」というクエリに、高速かつ構造的に答える層です。
減衰スコアリング + supersedes は A-MEM の Ebbinghaus モデルをプロジェクトメモリに適用したものです。supersedes パスは精神的には Mem0 の「ADD / UPDATE / DELETE」メモリ操作に近いですが、その場での書き換えではなく純粋なエッジとして表現されています。
EDC によるスキーマドリフト は EMNLP'24 の Extract-Define-Canonicalize と同じ着想を、関係抽出ではなくオントロジー進化に適用したものです。

Tesserae 固有のまま残り、防衛可能なくさび（ウェッジ）であり続けるもの: あらゆる場所での型付きエッジ、ファーストクラスのグラフノードとしてのセッション所見、そして（今や）同じグラフ内のコードシンボル です。2026 年の競合の多くは型付きエッジを完全に欠いています。それを持つ少数の中でも、散文の決定をコードシンボルへリンクするものはありません — v0.2.0 で敷かれた feat/code-graph の土台は、このくさびが複利的に効き始める場所です。

参考:

Architecture overview — モジュールマップとパイプライン
Feature map — ソースリンク付きの全機能ステータス表
Sessions integration — decay と supersedes が動作するセッショングラフ機能
MCP integration — MCP ツールの全リスト（新しい 4 ツールは次のドキュメント反映で追加されます）

v0.2.0.ja.md

Tesserae v0.2.0 — 型付き検索、コードグラフ、オントロジー進化

1. graph_ppr — 型付きグラフ上の Personalized PageRank

これは何か

使い方

いつ使うか

実装場所

注意点

2. ハイブリッド search_nodes — BM25 + lexical + embedding を RRF で融合

これは何か

使い方

どのモードをいつ使うか

実装場所

注意点

3. tesserae project ingest-code — Python AST から型付きコードグラフへ

これは何か

使い方

いつ使うか

実装場所

注意点

4. コミュニティサマリー — Louvain + LLM（オプトイン）

これは何か

使い方

いつ有効にするか

実装場所

注意点

5. 減衰スコアリング + supersedes + fresh_insights

これは何か

使い方

supersedes パスをいつ有効にするか

実装場所

注意点

6. tesserae project schema-drift — EDC による enum 提案

これは何か

使い方

いつ使うか

実装場所

注意点

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

戦略的コンテキスト

1. `graph_ppr` — 型付きグラフ上の Personalized PageRank

2. ハイブリッド `search_nodes` — BM25 + lexical + embedding を RRF で融合

3. `tesserae project ingest-code` — Python AST から型付きコードグラフへ

5. 減衰スコアリング + `supersedes` + `fresh_insights`

6. `tesserae project schema-drift` — EDC による enum 提案