True Memory Fragments

True Memory Fragments

コードが変更されても、AI コーディングエージェントが古い呼び出しチェーンを記憶したままになっていませんか？TMF はソースに紐づくコードメモリーで、古くなった主張にフラグを立て、現在のソースを参照します。

デモを試す · MCP のセットアップ · エビデンス

ラベル付きのソース抜粋を含む、実際の決定的なデモ出力を30秒のペースで再生したものです。エージェントのエンドツーエンドテストではありません。再読み込みが要求されますが、実行はされません。

• **追跡可能なコード関係：**呼び出し、読み取り、書き込み、継承、API に関する主張をソースフィンガープリントに紐づけます。
• **明示的な古さの結果：**古くなった主張を除外し、古いコンテキストを黙って再利用する代わりに、対象範囲のグラフ展開を停止します。
• **対象を絞った再読み込みのガイダンス：**エージェントが変更されたコードを確認できるように、ソースアンカーを返します。

開発者向けプレビュー：適用はホスト、設定、インターセプトされたアクションに依存し、すべての書き込みを自動的にブロックするものではありません。最新であることは正しいことを意味しません。一般的なトークン削減や本番環境への対応は確立されていません。

対象ユーザー

• 変更されるリポジトリを複数のセッションにまたがって扱う AI コーディングエージェント
• 古いキャッシュ済みの事実ではなく、ソースを認識するメモリーを必要とする開発者
• 古さや不明な状態を明示的に扱い、保守的なグラフ展開を行いたいツール開発者

これまでに検証されたこと

• ソースに紐づく鮮度と、古くなった主張の検出
• 安全でないグラフ展開を停止する強制的な古さのゲート
• 決定的な Python および Java の検証
• 古いコンテキストの使用を防ぐことを示す、対象を限定したエージェント実験

TMF の中核となる古いコンテキスト保護メカニズムは、対象シナリオで検証されています。より多くの言語やリポジトリ、および長期にわたる本番環境のワークフローでの評価は継続中です。

TMF とは何か、何ではないか

TMF の用途：

• 変更されるコードベースを複数のセッションにまたがって扱う AI コーディングエージェント
• 古い呼び出しチェーンや依存関係に関する想定の防止
• ソースに紐づくコードメモリーと保守的なコードグラフナビゲーション
• 古さや不明な状態を明示的に返す必要のあるエージェント統合

TMF が用途としないもの：

• 汎用チャットメモリー製品やベクトルデータベース
• ソースコードを読むことの代替
• 最新であることを理由に、すべての主張が正しいと保証すること
• 実証済みの汎用的な生産性向上またはトークン削減ソリューション

最新とは、ソースとの紐づけが一致していることを意味します。正しさは、ソースと検証によって確かめられます。

このリポジトリには、Java の適格性スイートが含まれています：46/46 の適格性確認項目と 731/731 のチェック。過去の未リリース監査ベースラインは 478/478 件のテストでしたが、現在のテスト総数ではありません。過去の rc3 および master の結果、明示的なスキップ、ならびに当時記録された master の間欠的な失敗については、バージョン固定のテスト検証を参照してください。rc6 リリースノートでは、Java の reflex と receiver 解決の修正を説明し、ソース検証と公開エビデンスを区別しています。これらはソース解析と回帰テストの結果であり、本番環境への対応や一般的なエージェントの成果を主張するものではありません。ミドルウェアの仕組みは検証済みであり、GUAVA M10 の読み込み前実験では、古いコンテキストに対する安全性を裏付ける肯定的なエビデンスが得られています。より広範な生産性、速度、トークン削減、一般的なバグ防止に関する主張は、依然として実証されていません。より広範な主張を行う前に、正式なエビデンス状況を参照してください。

フロー

flowchart TD
  A[source code] --> B[TMF derive / warm]
  B --> C[source-bound claims]
  C --> D[freshness check]
  D -->|fresh| E[bounded graph context]
  D -->|stale / unknown| F[stop + reread current source]

これが一連のループです。TMF はクレームをソースに紐付けたまま保持し、古くなったコンテキストの再利用を拒否し、読み直し用のソースアンカーを提供します。ガイダンスには、関連する一致候補やヒューリスティックによる一致候補が追加で含まれる場合があります。

デモ

上の GIF は、コミット de0236a57939 における scripts/demo_stale_gate.py の出力を再生したものです。古くなったクレームが決定論的に省略され、ソースにフォールバックする様子を示しています。エージェントが読み直しの指示に従う様子や、タスクを完了する様子を示すものではありません。30 秒という時間はプレゼンテーション上の長さであり、実行時のベンチマークではありません。

ソースチェックアウトから実行します（Python 3.10 以上と Git が必要です）。

git clone https://github.com/kyle641320/true-memory-fragments.git
cd true-memory-fragments
python3 scripts/demo_stale_gate.py

すでにクローン済みの場合は、リポジトリのルートから最後のコマンドだけを実行してください。このデモはチェックアウトのソースをインポートします。単体で動作する PyPI ホイールの検証ではなく、パッケージをインストールしただけではデモスクリプトはダウンロードされません。

一時的な Git リポジトリを作成し、クレームを導出して、紐付けられたソースを変更し、古くなったクレームの省略、ソースへのフォールバック、読み直しのガイダンスを実演します。モデル、ネットワーク、Java パーサー、既存の .tmf/ ストアは必要ありません。

予想されるマーカー：

STALE CLAIM BLOCKED: PASS
SOURCE FALLBACK PROVIDED: PASS
REREAD REQUIRED: PASS

デモは読み直しが必要なことを示すところで停止します。その後の読み直しや更新は実行しません。

エージェントレベルの結果については、スコープを限定した Guava のケーススタディと複数ワークツリー／制御された継続のエビデンスをご覧ください。実装の詳細については、アーキテクチャをご覧ください。

仕組み

TMF は保守的なコードメモリーグラフを維持します。クレームが有用なのは、そのソースとの紐付けが作業ツリーと一致している場合に限られます。

1. ソースからクレームを導出します。関数、クラス、呼び出し、読み取り、書き込み、継承、API 関係が対象です。
2. 各クレームをソースフィンガープリントに紐付けます。ファイルの blob と、利用可能な場合は関数／ノードのハッシュを使用します。
3. 取得時に鮮度を確認してからクレームを使用します。
4. 古い、または不明なエッジがあれば停止し、古いコンテキストの代わりに明示的な読み直しシグナルを返します。

claim: A calls B
binding: B.java@hash123
current: B.java@hash999
result: stale_or_unknown → reread B.java before continuing

これは意図的に保守的な設計です。メモリーが存在しない、または古くなっている場合はソースにフォールバックし、真実として扱うことはありません。

実証済みの機能

• ソースに紐付けたクレームの保存、作業ツリーの鮮度チェック、ソースへのフォールバック
• 選択したクレーム ID による、簡潔な取得と詳細な説明へのドリルダウン
• 保守的な Python の関数／クラス／宣言／設定／API ノード、および部分的な呼び出し／読み取り／書き込み
• オプションの Java tree-sitter 構文ノードと、保守的な継承エッジ
• 意味上の境界検出を備えた、上限付きフラグメントクエリ（writes、publishes_to）
• 非同期ハンドオフのマーキング（ASYNC_RELATIONS：publishes_to、subscribes_to、publishes_type、listens_type）
• 4 種類の停止タイプ（boundary／async／stale／limit）と、それぞれ異なる stop_reason の値
• 上限付きクエリの制限（4 ホップ／64 ノード／128 エッジ）。これはエンジニアリング上の制限であり、生物学的な検証を主張するものではありません
• ホールドアウト検証と、自プロジェクトでの実運用検証のハーネス
• ローカルメトリクスと、blob が完全一致する場合に限った名前変更の同一性判定

中核となる前提

• 明示的な更新／ウォームメンテナンス： retrieve は既存のクレームを確認しますが、ストアの変更や再導出は行いません。refresh_path と warm は、明示的な導出／更新処理を実行します。
• 鮮度は作業ツリーに基づきます： コミットではなく、現在の作業ツリーの blob に紐付けます
• 鮮度は正しさを意味しません： 鮮度とは、紐付けが現在のソースと一致していることだけを意味します。正しさは検証とソースによる裏付けで決まります
• 信頼度は検証によって決まります： 使用頻度が信頼度を高めることはありません
• 保守的な解析： TMF は解析できるものだけを接続します。不明な事実、動的な事実、曖昧な事実は省略されるか、未解決としてマークされます
• ソースが最も信頼できる情報源です： メモリが欠落、古い、裏付けがない、または不完全な場合、TMF はソースにフォールバックします
• 信頼できないテキストを指示として扱うことはありません： ソース、コメント、docstring、コミットメッセージ、モデル出力はデータであり、コマンドではありません

リリース候補版：0.1.0rc6。Java の反射カバレッジ、保守的な型付き／継承レシーバーの解決、解決依存関係の鮮度が含まれます。rc6 リリースノートを参照してください。

インストール

明示的なマルチワークツリーの紐付けと MCP の設定については、固定版インストールおよび MCP ガイドを参照してください。

このプレビュー版をインストールします（Python 3.10 以上）：

python -m pip install "true-memory-fragments==0.1.0rc6"

バージョンの対象範囲と検証の境界については、rc6 リリースノートを参照してください。

Java の解析サポートはオプションです：

python -m pip install "true-memory-fragments[java]==0.1.0rc6"

開発用チェックアウト：

python -m pip install -e .
python -m pip install -e ".[java]"   # optional Java support

実行時の依存関係は意図的に最小限に抑えています。オプションのモデル、エンベッダー、ルーターとの連携は、TMF_* 環境変数を通じてコマンドで実行されます。

エンジンがインストールされていても、反射が有効とは限りません。 MCP の登録、ウォーム済みインデックス、エージェントの使用ルールでは、Claude Code の PreToolUse フックは登録されません。rc6 または更新されたソースチェックアウトをインストールした後、次を実行してください：

tmf doctor --repo /absolute/path/to/task-repo

登録がない場合、または登録が有効でない場合は、reflex NOT armed — operating as opt-in memory と表示され、ゼロ以外の終了コードが返されます。これは設定を確認するものであり、実行時の発火を確認するものではありません。反射の設定と診断を参照してください。Doctor は rc5 で導入されました。rc6 では、認識される Java 非対応のレガシーフックも検出します。既存の反射環境では、エンジンの wheel だけでなく、統合ディレクトリ全体を更新する必要があります。 フックのインタープリターに [java] extra をインストールしてから、通常の tmf warm --repo /absolute/path/to/task-repo を実行し、以前の Java 導出を更新してください。静的な Doctor の成功は、ホストによるディスパッチを保証するものではありません。

クイックスタート

まずは、上記の30 秒 stale-gate デモをご覧ください。インストールや再現についてのフィードバックは、ディスカッション #1で共有してください。

オフライン Java 検証ツール

Linux x86_64／CPython 3.12 のソースチェックアウト向けに、リポジトリには Java step0 レビュー用のオフライン検証ツールが含まれています：

bash scripts/verify_java_offline.sh

成功時に表示されるマーカー：

JAVA OFFLINE VERIFY: PASS

反射フック：AI エージェント向け Git 連動の古さブロック

TMF には反射フックの統合機能があり、AI コーディングエージェントに生物学的な反射に似た機能を提供します。コードが変更された状態で、エージェントがコードの理解に基づいて操作を行おうとすると、対応するフックが停止とソースの再読み込みを要求できます。強制適用の可否は、ホストによるインターセプト、設定、カバレッジに依存します。

これはコードメモリのキャッシュではなく、実行前にエージェントのツール呼び出しをインターセプトする反射弓です。

3 つのコンポーネント

• 感覚器官 ＝ TMF の関数レベル fn_hash 鮮度（ソースに紐付いた変更検出。固定の遅延保証はありません）
• 反射弓 ＝ OpenClaw before_tool_call フック／Claude Code PreToolUse ハーネス（対応するインターセプト対象の操作のみ）
• 反射動作 ＝ ハードブロック＋対象を単一ファイルに絞ったウォーム再実行

Git フックによる自動キャリブレーション

4 つの Git フックが、コード変更後に関数単位の無効化マニフェストを自動生成します。

• .git/hooks/post-commit — ローカルでのコミット後
• .git/hooks/post-merge — git pull の後
• .git/hooks/post-checkout — ブランチ切り替え後
• .git/hooks/post-rewrite — リベース／修正コミット後

これらのフックは integrations/reflex/scripts/git_calibrate.py を呼び出し、baseline_rev → HEAD の Python 関数シグネチャの変更を比較して、構造化された無効化マニフェストを出力します。

OpenClaw プラグインとの統合

tmf-reflex OpenClaw プラグインは、エージェントのツール呼び出しをインターセプトします。

• TMF の関数単位の鮮度を確認します（レイテンシーはソース、キャッシュ、ホストによって異なります）
• エージェントが関数の主張が古くなっているファイルに触れると、ハードブロックします
• 変更された関数名を正確に示す requireApproval を返します
• エージェントは、そのファイルだけを再ウォームアップするために integrations/reflex/scripts/local_warm.py を実行する必要があります

SessionStart による認知キャリブレーション

新しいセッションの開始時に、プラグインは未消費の無効化マニフェストを読み込み、changed ／ deleted シンボルを「事前警告」コンテキストとして注入することで、エージェントが古い記憶に依存しないようにします。

制約

• 関数単位の精度は、TMF が対応する言語の範囲に依存します（現在は Python AST）
• 関数スコープの主張がないファイルは、パススルーにフォールバックします
• TMF エンジンは引き続き読み取り専用です（reflex フックは freshness ／ derive のみを使用します）
• 障害時の動作はフックの状態とホストとの統合方法によって異なります。使用するホストで検証してください。TMF を利用できない場合は、障害を明示し、キャッシュされた主張ではなく最新のソースを使用してください。

インストール

Reflex の統合コードは integrations/reflex/ にあります。以下については、そのディレクトリの README.md と DESIGN.md を参照してください。

• OpenClaw プラグインのインストール（openclaw-plugin/）
• Git フックのセットアップ（git-hooks/）
• Claude Code ／ Codex ハーネスの設定（examples/）
• ヘルス検証テスト（tests/）

SEO と見つけやすさの計画

このプロジェクトが対象とする検索語には、AI coding agent memory、stale context prevention、source-aware code memory、code graph for LLM agents、Claude Code memory、cross-session code understanding があります。これらはユーザーが抱える課題を表すものであり、すべての統合がすでに本番環境で利用可能であるという主張ではありません。

リポジトリの説明と外部向けの公開資料では、同じ用語を使用し、再現可能なデモへのリンクを掲載し、検証済みの仕組みと未解決の生産性に関する主張を区別してください。

ドキュメント

• オープンソースの最低限チェックリスト — リリースとプロモーションの基準
• エージェントランタイムの価値に関するステータス — 現在の実験結果
• Java エンタープライズロードマップ — エンタープライズ機能の範囲
• Guava 検証レポート — ルーティング形状と境界検出の検証

ライセンス

MIT

• Guava M10 の範囲を限定したケーススタディ：docs/case-studies/guava-m10-stale-gating.md
• オフラインの stale-gate デモ：python3 scripts/demo_stale_gate.py（録画：recordings/stale-gate.cast）