科学的インテリジェンスレイヤー

lean-ctx はパターンマッチングを超えています。情報理論、グラフ理論、統計力学の6つのアルゴリズムが連携して、何を残し、何を削り、どこに配置するかを決定します - すべて自動で、すべてローカルで、設定不要です。

これらのアルゴリズムは自律的インテリジェンスレイヤーを支えています。すべての ctx_read、ctx_preload、ctx_overview 呼び出し時に起動し、直接呼び出す必要はありません。

各レイヤーの相互作用

予測サプライズスコアリング

従来の圧縮フィルタは生の文字に対するシャノンエントロピーを使用し、aaaa と import を同等に予測可能として扱います。予測サプライズは代わりに BPE token頻度に対するクロスエントロピーを測定します - 各行が LLM のトークナイザーにとってどれだけ意外かを判定します。

仕組み

1. 各行は o200k_base（GPT-4o / Claude トークナイザー）を使ってトークン化されます。
2. 各tokenについて、ジフの法則に基づく事前分布がランクから期待頻度を推定します。
3. クロスエントロピーが計算されます：一般的なtoken（ボイラープレート）を持つ行は低スコア、珍しいtoken（複雑なロジック）を持つ行は高スコアになります。
4. サプライズしきい値を下回る行は、アグレッシブ圧縮時の除去候補になります。

例

// Low surprise (boilerplate) - candidate for removal:
return Ok(());                    // surprise: 0.12
use std::collections::HashMap;   // surprise: 0.18

// High surprise (unique logic) - always preserved:
let decay = (-alpha * dist as f64).exp();   // surprise: 0.89
scores[j] += heat[i] * decay / degree;      // surprise: 0.94

重要な理由

予測サプライズは、複雑なロジックを保持しながら、文字レベルのエントロピーより15〜30%多くのボイラープレートを除去します。同じ BPE 語彙を使用するため、LLM が「情報量が多い」と見なすものを直接モデル化します。

スペクトル関連度伝播

lean-ctx にタスクのコンテキストをプリロードするよう依頼すると、どのファイルが重要かを判断する必要があります。単純なキーワードマッチングでは検索語を含むファイルしか見つかりません。Spectral Relevance は、キーワードを共有していなくても、関連するファイルに構造的に接続されているファイルを見つけます。

仕組み

プロジェクトの依存関係グラフに対して2つのグラフアルゴリズムが実行されます：

1. 熱拡散 - タスクの説明に一致するシードファイルに初期「熱」が与えられます。熱はインポートエッジに沿って指数減衰しながら伝播し、コードベースを通じた情報の流れをシミュレートします。
2. PageRank 中心性 - 多くの他のファイルからインポートされているファイルは、より高い中心性スコアを受けます。これにより構造的なハブ（例：20のモジュールからインポートされる db.ts）が特定されます。

最終的な関連度スコアは両方を組み合わせます：0.7 × heat + 0.3 × pagerank。しきい値以下のファイルはプリロードから除外されます。

例

Task: "fix authentication bug"

Direct matches:       auth.ts, login.ts
Heat diffusion adds:  middleware.ts (imports auth.ts)
                      session.ts (imported by auth.ts)
PageRank promotes:    db.ts (imported by 18 files - structural hub)

Result: 5 files preloaded instead of 2, covering the full blast radius.

設定不要

依存関係グラフは初回使用時に load_or_build() で自動的に構築されます。ctx_graph build は不要です - そのまま動作します。

ボルツマンコンテキスト配分

Spectral Relevance が関連ファイルを選択した後、各ファイルにtoken予算を割り当てる必要があります。単純な方法では均等に予算を配分するか、関連度順に並べます。Boltzmann Allocation は統計力学を使って最適にtokenを分配します。

仕組み

1. 各ファイルには Spectral Relevance からの関連度スコア E_i があります。
2. 温度パラメータ β はタスクから導出されます：具体的なタスク（「login.ts の認証バグを修正」）は低温度（上位ファイルへの集中配分）を生み、広範なタスク（「コードベースをリファクタリング」）は高温度（均等配分）を生みます。
3. token予算はボルツマン分布に従います： budgeti = total × (eβ·Ei / Σ eβ·Ej)
4. 最小・最大予算（ファイルあたり128〜4096 token）が適用され、割り当て予算に基づいて圧縮モード（full、map、signatures）が選択されます。

例

Task: "fix the JWT validation in auth middleware"
Task specificity: 0.85 (specific) → β = 4.2

File            | Relevance | Budget | Mode
auth.ts         |      0.92 |  3,200 | full
middleware.ts   |      0.78 |  1,800 | full
session.ts      |      0.45 |    420 | map
db.ts           |      0.31 |    180 | signatures
routes.ts       |      0.22 |    128 | signatures
                                ─────
Total:                         5,728 tokens (within 8,000 budget)

Reciprocal Rank Fusion (RRF) Cache Eviction

lean-ctx uses Reciprocal Rank Fusion for cache eviction decisions, replacing the earlier Boltzmann-inspired weighted scoring. RRF handles incomparable signals (time in seconds, frequency as counts, size in tokens) without arbitrary weight tuning.

Formula: RRF(d) = Σ 1/(K + ranki(d)) - entries with the lowest fused score are evicted first. This produces monotonically correct ordering regardless of signal magnitude differences.

アテンションブリッジ付きセマンティックチャンキング

LLM は「中間の情報が失われる」問題を抱えています：コンテキストの最初と最後の情報は中間のコンテンツよりも多くの注意を受けます。セマンティックチャンキングは、情報損失を最小化するよう出力を再構成します。

仕組み

1. チャンク検出 - ソース行は AST バウンダリのヒューリスティクスに基づいてセマンティックチャンク（関数、型、インポート、その他のロジック）にグループ化されます。
2. 関連度順序 - 現在のタスクに一致するチャンクは先頭（高アテンション位置）に昇格されます。残りのチャンクはタイプの優先度順に並べられます。
3. アテンションブリッジ - チャンク間に、lean-ctx は最小限のブリッジマーカー（---）を挿入し、LLM が構造的な境界を認識できるようにします。
4. テイルアンカー - 最も優先度の高いチャンクの最後の2〜3行が出力の末尾に繰り返され、重要な情報に対するリーセンシーバイアスを活用します。

例

// Without chunking (flat output):
import { db } from '../pages/docs/db';
import { hash } from '../pages/docs/crypto';
const MAX_RETRIES = 3;
export function createUser(...) { ... }
export function validateToken(...) { ... }    ← lost in the middle
export function deleteUser(...) { ... }

// With semantic chunking (task: "fix token validation"):
export function validateToken(...) { ... }    ← promoted to top
---
export function createUser(...) { ... }
export function deleteUser(...) { ... }
---
import { db } from '../pages/docs/db';
const MAX_RETRIES = 3;
---
// anchor: validateToken signature                ← tail anchor

MMR 重複排除

複数のファイルがコンテキストに読み込まれると、重複したインポート、共通のボイラープレート、非常に類似したコードパターンが含まれることがよくあります。Maximum Marginal Relevance (MMR) は、固有の情報を保持しながらこの冗長性を除去します。

仕組み

1. 各行について、すでに選択された全行（「カバレッジセット」）に対するバイグラム Jaccard 類似度を計算します。
2. MMR スコアは関連性と冗長性のバランスを取ります： MMR(l) = λ × relevance(l) - (1 - λ) × max_similarity(l, selected)
3. MMR < 0 の行は抑制されます - 情報よりも多くの冗長性を追加するためです。λ パラメータのデフォルトは0.7（多様性よりも関連性を優先）です。

効果

一般的なマルチファイルプリロードでは、MMR は10〜25%の冗長コンテンツを除去します - 主に共有インポートや繰り返されるユーティリティパターンです。

BPE アラインドtoken最適化

すべてのコンテンツが選択・順序付けされた後、最終パスで LLM の BPE トークナイザー向けにテキストを最適化します。小さなフォーマット変更でも、意味を変えずにtoken数を大幅に削減できます。

最適化ルール

仕組み

各ルールは、他のすべての圧縮段階の後に行ごとに適用される単純な文字列置換です。ルールは BPE tokenバウンダリ分析から導出され、トークナイザーが意味的に同等のテキストに対して不必要に多くのtokenを生成するパターンを対象としています。

効果

BPE 最適化は、すでに圧縮された出力に対して通常3〜8%の追加tokenを節約します。節約はファイル間で複合的に蓄積され、冗長な言語（TypeScript、Java、C#）で最も効果的です。

効果の検証

プロジェクトで lean-ctx benchmark run を実行して、6つのアルゴリズムすべての複合効果を測定できます。ベンチマークレポートには、ファイルごとのtoken節約量、保存スコア（AST、識別子、行）、および全体的な圧縮率が表示されます。

$ lean-ctx benchmark run
──────────────────────────────────────────
BENCHMARK - /Users/you/project
──────────────────────────────────────────
Files:       143
Total:       285,401 → 42,810 tokens (85% reduction)
Avg/file:    1,997 → 300 tokens

Preservation:
  AST:         98.2%
  Identifiers: 97.4%
  Lines:       96.1%

Mode breakdown:
  full:        68% of files
  map:         22% of files
  signatures:   8% of files
  aggressive:   2% of files

構造化インテント認識

lean-ctxは各インタラクションをStructuredIntentに分類します - タスクタイプ、信頼度、対象ファイル、スコープ、言語ヒント、緊急度、アクション動詞を含むスロットベースの表現です。これがすべての下流の決定を駆動します：どの圧縮モードを使用するか、コンテキストをどうルーティングするか、何を優先するか。

9つのタスクタイプが認識されます：Explore、Generate、FixBug、Refactor、Test、Review、Config、Deploy、Document。各タイプが異なる圧縮戦略とコンテキストルーティングをトリガーします。

IntentScopeはSingleFileからMultiFile、CrossModuleを経てProjectWideまで - コンテキスト収集の幅を決定します。

仕組み

圧縮はインテントごとに適応：FixBugタスクはInformation Bottleneckフィルターでエラー行とテストファイルを優先、Exploreタスクは構造を保持する軽量クリーンアップを使用、Generateタスクはシグネチャとタイプに焦点。

ctx_readの自動モードセレクターはアクティブなタスクタイプを使用して判断を精緻化 - 大きなファイルでのバグ修正にはtaskモード、探索にはmapモード、ドキュメント作業にはsignaturesモードを選択。

例

Query: "fix the NaN bug in entropy.rs"

StructuredIntent:
  task_type:    FixBug (confidence: 0.95)
  targets:      ["entropy.rs"]
  scope:        SingleFile
  language:     Rust
  urgency:      0.8
  action_verb:  "fix"

→ Compression: Information Bottleneck filter (error lines boosted)
→ Mode:        task (error-focused extraction)
→ Suggestions: tests/entropy_test.rs (deficit detection)

コンテキストパイプラインアーキテクチャ

コンテキストパイプラインは6つの異なるレイヤーを通じて情報を処理：Input → Intent → Relevance → Compression → Translation → Delivery。各レイヤーには定義された契約（入出力タイプ）があり、メトリクスを出力します。

仕組み

Input → Intent → Relevance → Compression → Terse Engine → Delivery
  │        │          │            │              │              │
  │        │          │            │              │              └─ Final output to LLM
  │        │          │            │              └─ 4-layer terse pipeline (see below)
  │        │          │            └─ AST-aware compression per intent
  │        │          └─ Graph heat + relevance scoring
  │        └─ StructuredIntent classification
  └─ Raw file content / shell output

レイヤーごとのメトリクスは入力トークン、出力トークン、圧縮率、処理時間を追跡。セッション全体で集約すると、最大の節約がどこで発生し、どのレイヤーがボトルネックかを明らかにします。

4-Layer Terse Engine

The terse engine applies four composable compression layers, controlled by compression_level (Off / Lite / Standard / Max). Each layer is independently verified by Lean4 proofs (TerseQuality, TerseEngine — part of 82 total theorems).

コンテキスト台帳と圧力管理

ContextLedgerはAIに送信されるすべてのファイルを追跡：パス、圧縮モード、元のトークン、送信トークン、タイムスタンプ。コンテキストウィンドウの使用率と圧力をリアルタイムで計算します。

仕組み

3つの圧力レベル：None（使用率70%未満）、Compress（70–90%）、Evict（90%超）。各レベルでシステムは異なるアクションを実行 - 関連性の低いファイルの圧縮モードダウングレードやエビクション提案。

例

Context Window: 128,000 tokens
Loaded: 89,600 tokens (70% utilization)
Pressure: None → safe

After loading 3 more files:
Loaded: 115,200 tokens (90% utilization)
Pressure: Compress → downgrade non-target files

Re-Injection Plan:
  utils.rs:    full → signatures  (save 2,400 tokens)
  helpers.rs:  full → map         (save 1,800 tokens)
  config.rs:   full → signatures  (save 1,200 tokens)
  Protected:   auth.rs, login.ts  (target files)

コンテキスト不足検出は欠落情報を特定：バグ修正タスクがauth.rsを対象としているのにテストファイルが読み込まれていない場合、システムはtests/auth_test.rsを提案。設定タスクにはCargo.toml、.env、Dockerfileを推奨。

スマート再注入は、非対象ファイルのダウングレード（例：fullモードからsignaturesモードへ切替）によりコンテキスト予算を解放するプランを生成 - 現在のインテントに重要なファイルを保護しつつ。

マルチエージェントインテリジェンス

複数のAIエージェントが協業する場合（例：コーダーとレビュアー）、lean-ctxは構造化ハンドオフ、ロールベースのコンテキスト深度、エージェント間知識共有を提供します。

仕組み

HandoffPackageは現在のセッション台帳、構造化インテント、コンテキストスナップショットを単一の転送可能ユニットにバンドル - 受信エージェントが白紙からではなく完全な状況認識で開始できるように。

7つのエージェントロールが認識されます：Coder、Reviewer、Planner、Explorer、Debugger、Tester、Orchestrator。各ロールはカスタマイズされたContextDepthConfigを受け取ります - コーダーはより多くのフルファイル読み込み、レビュアーはより多くのシグネチャ、エクスプローラーはより広いグラフコンテキスト。

例

Agent "coder-1" (role: Coder):
  max_files_full: 8
  preferred_mode: full
  context_budget: 80%

Agent "reviewer-1" (role: Reviewer):
  max_files_full: 3
  preferred_mode: signatures
  context_budget: 60%

Shared Knowledge:
  K:discovery:auth_bug = "null check missing in line 42"
  K:decision:fix_approach = "add Option<T> wrapper"
  → reviewer-1 inherits these facts without re-reading files

エージェント間知識共有により、エージェントは共有スクラッチパッドを通じて構造化ファクト（例："discovery:auth_bug=42行目でnullチェック欠落"）を交換できます。新しいエージェントは再発見することなく関連知識を継承します。

Community Detection (Louvain)

The core::community module clusters files by their dependency graph using the Louvain algorithm. This groups tightly-coupled files into communities, enabling more intelligent context selection — files in the same community as your target are prioritized for preloading and receive higher relevance scores during task-driven reads.

Code Smell Detection

The ctx_smells tool detects long functions, deep nesting, and high cyclomatic complexity using the core::smells module. Detected smells are scored with graph-enriched weighting — files with high PageRank or many dependents receive amplified smell scores, surfacing maintenance hotspots that have the widest blast radius across the codebase.

関連項目

• 自律インテリジェンスツール - これらのアルゴリズムを使用するツール
• tree-sitter エンジン - 18言語の AST 解析
• 設定 - しきい値と自律設定のチューニング
• ベンチマーク - 節約量の測定