korg-introspect-mcp

korg

AI エージェント向けの、改ざんの痕跡が残る SHA-256 チェーン型台帳です。 エージェントが実行するすべての手順を、誰でも検証できるハッシュチェーンに記録します。イベントを1つ編集すると、チェーンがそれを特定します。記録元を信頼する必要はなく、ブロックチェーンも不要です。

英語 · 简体中文 · 繁體中文

---

30秒で始める

スタンドアロンの検証ツールをビルドし（初回は約10秒。台帳のクレートのみをコンパイルします）、記録済みの Claude Code セッションを検証してから、イベントを1つ書き換え、チェーンがそれを検出する様子を確認します。

git clone https://github.com/New1Direction/korg && cd korg
cargo build --release -p korg-verify
cp spec/korg-ledger-v1/web/samples/session.jsonl /tmp/session.jsonl

./target/release/korg-verify /tmp/session.jsonl
#  ✓ journal VALID — 6 events, hash-chain + DAG intact

sed -i.bak '4s/return a - b/return a + b/' /tmp/session.jsonl   # rewrite the agent's edit

./target/release/korg-verify /tmp/session.jsonl
#  ✗ journal INVALID — 1 problem(s):
#      - seq 4: entry_hash mismatch (content was tampered)     (exit 1)

Rust のツールチェーンがない場合は、同じファイルをブラウザー内検証ツールにドロップしてください。ローカルで実行され、データは送信されません。

---

3社のエージェントで検証済み（N=3）

同じ korg-ledger@v1 形式で、アーキテクチャの異なる3つの本番エージェントのトレースを取り込み、因果構造（仕様 §2a）を往復変換後も保持します。

エージェント	トランスポート	ツール形式	アダプター	テスト
Claude Code	ディスク上の JSONL ＋ ライブフック	Anthropic の tool_use / tool_result ブロック	adapters/claude-code — 実際の3,141イベントのセッションでスモークテスト済み。欠落はゼロ	58 ✓
OpenAI Codex CLI	WebSocket フレーム	OpenAI の function_call ＋自由形式の custom_tool_call	adapters/codex-ws	11 ✓
Grok Heavy	NDJSON ストリーム	16エージェントの並列ファンアウト	adapters/grok-heavy	14 ✓

3つすべてが1つの形式に集約されるため、1つの検証ツールですべてを検証できます。Rust、Python、JS の実装はバイト単位で同一であり、相互に差分ファジングを行っても不一致は0件です。既知の制限は隠さずに明記しています。Grok Heavy の制限事項（取り込み順と実際の並行実行の違い、エージェント間のチャットルームのエッジ）を参照してください。

---

デモ全編：記録 → 検証 → 巻き戻し

---

AI エージェントはブラックボックスです。失敗しても、デバッグできません。成功しても、再現できません。 誤った操作をしても、取り消せません。

Korg がこれを解決します。

---

Korg が行うこと

メモ

ユニバーサル取り込み統合モード： Korg v1 は、MCP から呼び出し可能な監査シンクです。MCP 互換のコーディングエージェント（Claude Code、Codex など）は、korg のツールを呼び出して、セッションを因果関係がリンクされた、再生可能かつ巻き戻し可能な台帳に記録できます。エージェントには、操作を記録するよう指示する必要があります。通常は、システムプロンプトまたは MCP サーバーの設定で指示します。エージェントの協力なしに完全に受動的な監査を行う機能は、今後のバージョンでの実装を予定しています。

警告

信頼境界とデプロイ範囲： Korg v1 は、ローカルのシングルユーザーワークスペース専用に設計されています。マルチテナントおよびネットワーク環境へのデプロイには、まだ実装されていない暗号認証とアクセス許可の制限が必要です。信頼できないネットワークやパブリックネットワークでサーバーを実行すると、ワークスペースへの読み書きアクセスが公開されます。

Korg は 認知ハイパーバイザー です。AI エージェントの下層で動作し、エージェントが行うすべての判断を統制するランタイムレイヤーです。

LLM に取って代わるのではありません。LLM の動作を統制します。

Foundation Model          →  predicts, suggests, generates
────────────────────────────────────────────────────────────
Korg Cognitive Runtime    →  schedules, validates, isolates,
                             reconciles, replays, heals, governs

すべてのエージェントの操作は、次のとおりです。

• 不変で、暗号署名された台帳に 追記 されます
• ハイブリッド論理時計（因果的、決定論的、グローバルに一貫性を保つ）によって 順序付け されます
• 再生可能 です。履歴上の任意の時点の状態を正確に再構築できます
• 取り消し可能 です。台帳を過去の任意のシーケンス地点まで巻き戻せます

---

タイムトラベルのデモを試す

組み込みのサンドボックスデモを実行して、認知のタイムトラベルがどのように機能するかを確認できます。このデモでは、一時的なワークスペースにバグのある Python スクリプトを用意し、シミュレートされたコーディングエージェントに誤った編集を行わせ、テストの失敗を検出し、編集前の状態にワークスペースと台帳を巻き戻してから、正しい修正を投機的にコミットします。

cargo run -- demo

次のタイムトラベルの流れを、カラー表示で完全に確認できます。

⚡ STARTING KORG COGNITIVE TIME-TRAVEL DEMO ⚡
────────────────────────────────────────────────────────────────────────────────
[korg] Initializing sandboxed demo environment...
[korg] Created temporary workspace with math_utils.py (subtraction bug present).

🚀 PHASE 1: AGENT INITIATES RUN (WRONG PATH)
  [seq 390] actor: agent:[email protected] | tool: user_prompt | prompt: "Fix subtraction bug and verify tests pass"
  [seq 391] actor: agent:[email protected] | tool: Read        | file: math_utils.py
  [seq 392] actor: agent:[email protected] | tool: Edit        | result: "Modified return a + b (wrong fix)"
  [seq 393] actor: agent:[email protected] | tool: Bash        | command: "pytest" -> ❌ FAILED (2 tests failed)

📊 LEDGER STATE (BEFORE REWIND):
  Before rewind: events 390-393 (prompt, read, edit-wrong, test-failed)
    ├── seq 390 (user_prompt) -> triggered_by: None
    ├── seq 391 (Read) -> triggered_by: Some(390)
    ├── seq 392 (Edit) -> triggered_by: Some(391)
    ├── seq 393 (Bash) -> triggered_by: Some(392)

⏳ PHASE 2: INITIATING REVERSIBLE REWIND TO SEQ 391
  [korg] Truncating journal ledger to sequence ID 391...
  [korg] Restoring workspace snapshot via git read-tree (O(1))...
  [korg] Reset math_utils.py file state back to sequence 391 bug state.
  [korg] Rebuilding 3 read-model projections...

📊 LEDGER STATE (AFTER REWIND):
  After rewind:  events 390-391 (prompt, read)
    ├── seq 390 (user_prompt) -> triggered_by: None
    ├── seq 391 (Read) -> triggered_by: Some(390)

🚀 PHASE 3: AGENT DIVERGES DOWN CORRECT PATH (SPECULATIVE REPLAY)
  [seq 392] actor: agent:[email protected] | tool: Edit        | result: "Modified return a - b (correct fix)"
  [seq 393] actor: agent:[email protected] | tool: Bash        | command: "pytest" -> ✓ PASSED (2 passed)

📊 LEDGER STATE (AFTER DIVERGENT RUN):
  After new run: events 390-393 (prompt, read, edit-right, test-passed)
    ├── seq 390 (user_prompt) -> triggered_by: None
    ├── seq 391 (Read) -> triggered_by: Some(390)
    ├── seq 392 (Edit) -> triggered_by: Some(391)
    ├── seq 393 (Bash) -> triggered_by: Some(392)

✓ DEMO COMPLETE: Time-travel execution succeeded!
  Ledger truncated, workspace rolled back, and a different future was successfully committed.

これを実現できる AI エージェントのランタイムは、ほかにありません。

---

コアアーキテクチャ

Korg は、データベースやオペレーティングシステムの信頼性を支えるものと同じ理論的基盤の上に構築されています。それを AI の認知に初めて応用しています。

不変条件	意味
追記専用 WAL	すべての認知イベントが台帳のエントリになります。変更されることはなく、追記のみが行われます。データベースの WAL に似ていますが、AI の思考を対象としています。
HLC 因果順序	ハイブリッド論理時計により、分散したスウォームワーカー間でも、イベントストリームのグローバルな一貫性と因果順序が保証されます。
決定論的リプレイ	すべてのキャンペーンを台帳からバイト単位で再生できます。常に同じ入力から同じ出力が得られます。
投機的ブランチ	実行を並列の仮想パスに分岐します。コミット前にプレビューでき、自由に破棄できます。
実行チェックポイント	台帳オフセット、プロジェクションビュー、リースマップ、ワークスペースツリーなど、ランタイムの状態全体をスナップショットします。O(1) で復元できます。
マイクロヒーリング	一時的な障害（ロックの競合、古い状態）は、エフェクトレベルで自動的に修復され、リトライの監査証跡も完全に記録されます。
セマンティックガバナンス	スウォームの操作は、BERT 埋め込みのコサイン類似度を使って検証されます。キーワードの照合ではなく、意味的な整合性を確認します。

┌────────────────────────────────────────────────────────────────┐
│  korg v0.1.0  │  session: 019e5333-efc9-7c70  │  ● ACTIVE      │
├───────────────────────────────┬────────────────────────────────┤
│  SWARM PLAN                   │  LIVE MERKLE LEDGER            │
│  ├─ [●] Captain  [PLANNING]   │  (tx_00)→(tx_01)→[tx_02]→...  │
│  ├─ [●] Harper   [RESEARCH]   │                                │
│  ├─ [●] Benjamin [SYNTHESIS]  │  TELEMETRY                     │
│  └─ [○] Lucas    [IDLE]       │  ├─ Velocity  85.2 t/s  ▇▆▄▂█  │
│                               │  ├─ Entropy    0.451     ▄▃▂▃▄  │
│  GOVERNANCE GATES             │  └─ Progress  68.7 %    ▂▃▄▅▆▇  │
│  ├─ 🟡 Amber Security [IDLE]  │                                │
│  ├─ 🟢 Consensus     [ACTIVE] │  LEDGER STREAM                 │
│  └─ 🔵 Steering Fork [IDLE]   │  [tx_03] Benjamin: patch auth  │
└───────────────────────────────┴────────────────────────────────┘

---

クイックスタート

ソースからビルドする

このクレートはまだ crates.io に公開されていません。ソースからインストールしてください。

git clone https://github.com/New1Direction/korg
cd korg
cargo build --release
./target/release/korg --help

Python ブリッジ（korgex / korgchat 用）

cd crates/korg-bridge
maturin develop  # builds the PyO3 extension into the active venv
python3 -c "import korg_bridge; print(korg_bridge.__version__)"

最初のキャンペーンを実行する

# Interactive TUI dashboard
korg campaign --tui --prompt "Refactor the auth layer to use JWTs"

# Web cockpit at localhost:8080
korg campaign --web --prompt "Optimize the database connection pool"

# Pure autonomous goal mode (--goal is a top-level flag). Each persona works in
# its own git worktree and runs a real `cargo check`, so on a large repo a cold
# run takes minutes; `--speculative` pre-warms a shared target dir.
korg --goal "Write and validate a full test suite for src/parser.rs"

# Run the full multi-persona swarm on a REAL local model — every persona
# (Captain, Harper, Benjamin, Lucas, Evaluator) runs as a real worker
# subprocess doing real, measured, attested work. Defaults to a hermetic
# deterministic provider; `--provider ollama` makes it live.
korg --goal "Fix the failing test in src/lib.rs" --provider ollama --model qwen2.5:7b

# Preview without committing (dry-run; --preview is a top-level flag)
korg --preview "Refactor the main event loop"

巻き戻しと検証

# Rewind the capability journal (.korg/capability_journal.json) to a prior
# sequence point. It is populated by campaigns (`korg --goal`, `korg campaign`);
# on a fresh checkout there is nothing to rewind yet — `korg demo` shows the
# full rewind flow in a self-contained sandbox.
korg rewind --seq 4

# Drive the honest pipeline on a fixture and emit a verifiable ledger
korg run-once "Fix the add function in src/lib.rs so it adds"

# Same pipeline, but with a REAL local model (ollama) on an arbitrary task —
# the model writes the patch, Korg applies it, measures the real git diff +
# `cargo check`, and attests only what actually changed.
korg run-once "Fix the bug in src/lib.rs: max() returns the minimum.
Output the COMPLETE corrected src/lib.rs:
\`\`\`rust
$(cat your-repo/src/lib.rs)
\`\`\`" --repo your-repo --provider ollama --model qwen2.5:7b

# Independently verify any korg-ledger@v1 journal (no trust in the producer)
korg-verify <path-to-ledger.jsonl>

どのモデルでも、設計上誠実です。 デフォルトのプロバイダーは、隔離された決定論的スタブです（フィクスチャのみ、依存関係ゼロ）。--provider ollama を指定すると、あらゆるタスクで実際のローカルモデルが動作します。Korg は OpenAI 互換プロバイダーに厳密に有効な JSON（response_format: json_object）を要求するため、小規模な（7B）ローカルモデルでも、実際のパッチを確実に適用できます（qwen2.5:7b で 5/5 を測定）。どちらの場合も、証明は測定に基づくものであり、決して捏造されません。モデルがパッチを生成すると、台帳は実際の git diff のファイル数と変更されたパスを証明します。変更を拒否した場合や、コンパイルできない変更を書き込んだ場合は、Korg がその事実を正直に報告します（正直な null ― 変更数ゼロ、証明数ゼロ、または cargo check の失敗）。このパイプラインでは、作業ツリーに実際に示されていない数値を証明できません。これが、モデルの品質に左右されない保証です。

ブラウザーで検証できます ― 何も送信しません。 任意の korg-ledger@v1 ジャーナルまたは証明書を検証する、インストール不要のクライアントサイド検証ツール（Web Crypto）です。 セッションを検証 · 証明書を検証 · タイムトラベルエクスプローラー。 ハッシュチェーンを確認し、因果 DAG をチェックし、Ed25519 署名を検証し、イベントから人間向けの要約を再導出します。すべてローカルで実行されます。

推測的なブランチ／フォークと名前付きチェックポイント（korg fork、korg checkpoints list|restore）は計画中で、まだリリースされていません。現在利用できる巻き戻し機能は korg rewind です。

---

認知モード

Korg はタスクの複雑さに応じて、インテリジェンスのティアを調整します。モードは能力リゾルバーを通じてのみ制御され、切り替えはすべて台帳に記録されます。

モード	最適な用途
instant	超低レイテンシー。ネゴシエーションを省略します。楽観的に実行します。
balanced	デフォルト。構造化された複数ラウンドの契約ネゴシエーションを行います。
heavy	複数エージェントによる深い熟議。複数回の評価ラウンドを行います。
research	幅広く多様な探索。すべてのクレートを対象にセマンティックインデックスをスキャンします。
recovery	安全なロールバックモード。変更のたびにチェックポイントを作成します。
autonomous	完全な目標モード。自律的に進行し、自動で計画を立て直します。
heavy-consciousness	最大限の深度。HeavyConsciousness のコンテキストをすべて注入します。

korg --mode research "Explore alternative approaches to the rate limiter"
korg --mode recovery "Carefully migrate the database schema"

---

Korg が存在する理由

現在の AI コーディングエージェントは、確率的なブラックボックスです。エージェントは次のような問題を抱えています。

• 再生できません ― 同じプロンプトでも、毎回異なる出力になります
• 巻き戻せません ― 1 回の誤操作で、Git の履歴を手作業で差分比較することになります
• 監査できません ― エージェントが何を決定し、なぜそうしたかの記録がありません
• 統制できません ― 実行時にポリシーの境界を設定する手段がありません

Korg は、ハイパーバイザーがコンピューティングを、Git がコードを扱うのと同じように、AI の認知を扱います。

台帳に記録されていないことは、起きていないのと同じです。

---

比較

機能	Korg	LangChain / LangGraph	CrewAI	標準の CLI エージェント
決定論的な再生	✅	❌	❌	❌
因果 HLC 順序付け	✅	❌	❌	❌
実行の巻き戻し	✅	❌	❌	❌
推測的ブランチ	🚧 計画中	❌	❌	❌
実行チェックポイント	🚧 計画中	❌	❌	❌
暗号学的な監査証跡	✅	❌	❌	❌
独立して検証可能な証明書	✅	❌	❌	❌
正直な証明（実際の差分を使用し、決して捏造しない）	✅	❌	❌	❌
マイクロヒーリング	✅	❌	❌	❌
モデル非依存	✅	✅	✅	✅

Korg はエージェントフレームワークではありません。あらゆるフレームワークの下で動作するガバナンスカーネルです。

---

技術スタック

コンポーネント	テクノロジー
コアランタイム	Rust 2021、Tokio 非同期処理
台帳の順序付け	ハイブリッド論理クロック（HLC）
ワークスペースのスナップショット	Git Merkle ツリー（write-tree / read-tree による O(1) の復元）
暗号学的証明	Ed25519（ed25519-dalek）
セマンティックガバナンス	オプションの candle 機能を使った BERT のコサイン類似度（Hugging Face）。candle をビルドしない場合は、決定論的な埋め込みフォールバックが実行されます
TUI ダッシュボード	Ratatui + Crossterm
Web コックピット	Axum + SSE
構文ハイライト	Syntect + tree-sitter

---

アーキテクチャの詳細

→ 技術解説の全文を読む

実例：現実の監査台帳

Korg が生成した、現実の認知監査台帳を確認できます。この NDJSON ファイルには、Claude Code に Korg の MCP ツールを呼び出して関数をリファクタリングし、すべての呼び出し箇所の名前を変更するよう指示したライブセッションが記録されています。HLC の因果グラフ全体と actor_id レコーダーメタデータも含まれています。

• Claude Code セッション因果台帳（NDJSON）

概要：

1. CapabilityResolver — すべてのランタイム状態を管理する唯一の権限機関です。読み取りと書き込みはすべてここを経由します。副次的な状態ストアはありません。
2. CapabilityJournal — 追記専用の WAL です。すべての認知イベントは、HLC タイムスタンプ、因果関係の連鎖、暗号署名とともにここに封印されます。
3. ProjectionEngine — ジャーナルに対する純粋な状態の畳み込み処理です。任意の読み取りモデルを、生のイベントストリームから決定論的に再構築できます。
4. ExecutionCheckpoint — {ledger_offset, projection_state, lease_map, workspace_tree_hash} のスナップショットです。イベントストリーム全体を再生することなく、完全なランタイム状態を O(1) で復元します。
5. CapabilityExecutor — 物理的な効果 DAG を実行します。失敗した場合は、エスカレーションの前に自動的なマイクロ修復が行われます。

システム概要

flowchart TD
    Agent["MCP-compatible agent<br/>(Claude Code, Codex, korgex)"]

    subgraph Ingest["Ingestion paths"]
        MCP["mcp_server.py<br/>(MCP / JSON-RPC stdio sink)"]
        Bridge["korg-bridge<br/>(PyO3 in-process writer)"]
        Server["korg-server<br/>(Axum HTTP + SSE)"]
    end

    Journal["korg-registry · CapabilityJournal<br/>append-only WAL · HLC order · triggered_by DAG"]
    Chain["korg-ledger@v1<br/>hash-chain: prev_hash to entry_hash<br/>SHA-256 / HMAC + Ed25519"]
    Projection["ProjectionEngine<br/>pure folds to read models"]
    Rewind["rewind / rewind_with_seal<br/>truncate to seq + LedgerRewind tip"]
    Verify["korg-verify (+ Python / JS)<br/>verify_chain · verify_dag · sig · Certificate"]
    Runtime["korg-runtime<br/>multi-persona swarm · git-worktree sandbox<br/>arena · evaluator · run_once"]

    Agent --> MCP --> Journal
    Agent --> Bridge --> Journal
    Agent --> Server --> Journal
    Runtime --> Journal
    Journal --> Chain
    Journal --> Projection
    Journal --> Rewind
    Rewind --> Projection
    Chain --> Verify

---

ステータス

Korg は積極的に開発中です。**言語間の適合性を備えた凍結済みの korg-ledger@v1 仕様（Rust + Python + JS）**を基盤としています。テスト範囲は、ワークスペース全体の 300 件以上の Rust テストに加え、Python/JS 適合性テストスイートです。CI でビルド・テスト・言語間オラクル・差分ファズテストが実行され、main で成功しています。

リリース済み：

• HLC 順序付けを備えた、追記専用でハッシュチェーン化された認知台帳
• 決定論的な再生とプロジェクションの再構築
• 可逆的な実行 — 任意の過去のシーケンスポイントまで台帳を巻き戻し（改ざんを検知できる LedgerRewind）
• イベントごとの Ed25519 署名と構造的アンカリング（korg-ledger@v1 §8）
• Certificate（korgcert@v1） — エージェントの作業を証明する、公開され独立して検証可能な証明書。インストール不要のブラウザー内検証ツール付き
• 誠実なパイプライン（korg run-once）— 実際のパッチ → 実際の cargo check → 実際の git diff と一致する証明付きの変更数。捏造はせず、実態に即した null を報告します
• ライブローカルモデル（--provider ollama）— 任意のタスクに対して、ペルソナごとに実際の作業を実行
• マルチエージェントスウォーム（Captain、Harper、Benjamin、Lucas、Evaluator）— DAG によるペルソナ間のデータフローを備えた、実作業を行い、測定・証明するワーカープロセス
• Claude Code のゼロ設定キャプチャ（PostToolUse/Stop フック → セッションごとに検証可能な台帳を生成）
• マイクロ修復効果レイヤー · TUI ダッシュボード + Web コックピット
• 暗号学的プロベナンス証明 · 単一権限機関による CognitionMode ガバナンス
• プレビュー / ドライランモード（--preview）

予定 / 未リリース：

• 投機的ブランチ / フォーク + 実行チェックポイント復元 CLI（プリミティブは存在し、CLI は計画中）
• crates.io での cargo install korg · npm で公開する検証ツール
• ライブネットワーク・アンカリングリゾルバー（信頼できる時刻の証人 — 残された誠実な限界）
• リモートスウォームワーカー · WASM バックエンド · IDE 言語サーバー統合 · 分散チェックポイント同期
• エージェントの協力を必要としない、完全に受動的なキャプチャ

---

ライセンス

MIT または Apache-2.0 のいずれかをお選びいただき、そのライセンスの条件に従ってご利用ください。

---

_{Rust で構築。インバリアントに基づいて管理。ブラックボックスはありません。}