korg-introspect-mcp

korg

为 AI Agent 提供防篡改的 SHA-256 链式账本。 Agent 执行的每一步都会记录在哈希链中，任何人都能验证——修改一个事件，链就会指出它。无需信任记录者，也不需要区块链。

English · 简体中文 · 繁體中文

---

30 秒快速上手

构建独立验证器（冷启动约需 10 秒——它只会编译账本 crate），验证一段已记录的 Claude Code 会话，然后改写一个事件，看看链如何发现它：

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 工具链？将同一个文件拖入浏览器内验证器——它会在本地运行，不会发送任何内容。

---

已在三个厂商的产品中验证（N=3）

同一种 korg-ledger@v1 格式可接收来自三种架构各异的生产级 Agent 的追踪数据，并在往返过程中保留因果结构（spec §2a）：

Agent	传输方式	工具结构	适配器	测试
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 个 Agent 并行扇出	adapters/grok-heavy	14 ✓

由于三者都采用同一种格式，一个验证器就能检查全部数据——而且它有字节完全一致的 Rust、Python 和 JS 实现，这些实现经过彼此间的差分模糊测试，结果为 0 处差异。已知限制都明确记录，而非刻意隐瞒：请参阅 Grok Heavy 的限制（接收顺序与墙上时钟并发性、跨 Agent 聊天室边）。

---

完整演示：记录 → 验证 → 回退

---

AI Agent 是黑箱。它们出错时，你无法调试；它们成功时，你无法复现。 它们做错事时，你无法撤销。

Korg 解决了这个问题。

---

Korg 的功能

说明

通用接入集成模式： Korg v1 是一个可通过 MCP 调用的审计接收端。任何兼容 MCP 的编码 Agent（Claude Code、Codex 等）都可以调用 korg 的工具，将会话记录为因果关联、可重放、可回退的账本。必须指示 Agent 记录其操作，通常通过系统提示词或 MCP 服务配置实现。无需 Agent 配合的完全被动审计已列入未来版本的路线图。

警告

信任边界与部署范围： Korg v1 专为本地单用户工作区设计。多租户和联网部署需要尚未推出的加密身份验证和权限限制。在不受信任或公共网络上运行服务会暴露工作区的读写权限。

Korg 是一个认知虚拟机监控程序——位于 AI Agent 下层的运行时层，用于监管它们做出的每一个决策。

它不会取代你的 LLM，而是监管 LLM 的行为。

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

每个 Agent 操作都会：

• 追加到不可变、经加密签名的账本中
• 通过混合逻辑时钟（因果有序、确定性、全局一致）排序
• 可重放——在历史中的任意时点重建精确状态
• 可逆转——将账本回退到任意先前的序列位置

---

体验时空穿越演示

你可以运行内置的沙盒演示，查看认知时空穿越的实际效果。演示会创建一个包含有缺陷 Python 脚本的临时工作区，让模拟编码 Agent 做出错误修改，捕获测试失败，将工作区和账本回退到修改之前，然后通过推测提交正确的修复：

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 Agent 运行时能让你做到这一点。

---

核心架构

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  │
└───────────────────────────────┴────────────────────────────────┘

---

快速开始

从源代码构建

该 crate 尚未发布到 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——变更数为 0、证明数为 0——或 cargo check 失败）。流水线无法证明工作树中实际不存在的数字——这就是保证，与模型质量无关。

在浏览器中验证——不会发送任何内容。 零安装、在客户端运行（Web Crypto）的验证器，适用于任何 korg-ledger@v1 日志或证书： 验证会话 · 验证证书 · 时光穿梭浏览器。 它们会构建哈希链、检查因果 DAG、验证 Ed25519 签名，并根据事件重新推导出面向用户的摘要——所有操作均在本地完成。

推测性分支/分叉和命名检查点（korg fork、korg checkpoints list|restore）已列入计划，但尚未发布。目前可用的可逆操作是 korg rewind。

---

认知模式

Korg 会根据任务复杂度调整智能层级。模式完全由能力解析器管理——每次切换都会记录到账本。

模式	最适用场景
instant	超低延迟。绕过协商。乐观执行。
balanced	默认模式。结构化的多轮契约协商。
heavy	深度多 Agent 审议。多轮评估。
research	广泛的发散探索。扫描所有 crate 的语义索引。
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 编码 Agent 是概率式黑箱。它们：

• 无法重放——相同提示词，每次输出都不同
• 无法回退——一次错误操作，就得手动比对 Git 历史记录
• 无法审计——没有记录 Agent 做了什么决定以及原因
• 无法治理——无法在运行时设置策略边界

Korg 以虚拟机监控程序管理计算、以 Git 管理代码的方式管理 AI 认知：

未记录在账本中的事情，就没有发生。

---

对比

能力	Korg	LangChain / LangGraph	CrewAI	标准 CLI Agent
确定性重放	✅	❌	❌	❌
因果 HLC 排序	✅	❌	❌	❌
回退执行	✅	❌	❌	❌
推测性分支	🚧 计划中	❌	❌	❌
执行检查点	🚧 计划中	❌	❌	❌
加密审计追踪	✅	❌	❌	❌
可独立验证的证书	✅	❌	❌	❌
诚实证明（真实差异，绝不捏造）	✅	❌	❌	❌
微修复	✅	❌	❌	❌
模型无关	✅	✅	✅	✅

Korg 不是 Agent 框架，而是运行在所有框架底层的治理内核。

---

技术栈

组件	技术
核心运行时	Rust 2021、Tokio 异步
账本排序	混合逻辑时钟（HLC）
工作区快照	Git Merkle 树（通过 write-tree / read-tree 实现 O(1) 恢复）
加密证明	Ed25519（ed25519-dalek）
语义治理	通过可选的 candle 特性（Hugging Face）使用 BERT 余弦相似度；未构建 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）
• 证书（korgcert@v1） — 公开且可独立验证的 Agent 工作证书，配备无需安装的浏览器内验证器
• 诚实流水线（korg run-once）— 真实补丁 → 真实 cargo check → 与真实 git diff 变更数量相符的已证明变更计数；绝不捏造（而是如实报告 null）
• 本地实时模型（--provider ollama）— 面向任意任务，按角色执行真实工作
• 多 Agent 集群（Captain、Harper、Benjamin、Lucas、Evaluator）— 真正由工作者子进程完成真实、可度量且有证明的工作，并在各角色之间通过 DAG 传递数据
• Claude Code 零配置捕获（PostToolUse/Stop 钩子 → 可验证的单会话账本）
• 微修复效果层 · TUI 仪表板 + Web 控制台
• 加密溯源证明 · 单一权威的 CognitionMode 治理
• 预览 / 演练模式（--preview）

计划中 / 尚未交付：

• 推测分支 / 分叉 + 执行检查点恢复 CLI（基础构件已存在；CLI 计划中）
• 在 crates.io 上支持 cargo install korg · 发布到 npm 的验证器
• 实时网络锚定解析器（可信时间见证——剩余的一项诚实限制）
• 远程集群工作者 · WASM 后端 · IDE 语言服务器集成 · 分布式检查点同步
• 完全被动捕获，无需 Agent 配合

---

许可证

您可以选择遵循 MIT 或 Apache-2.0 许可证。

---

_{使用 Rust 构建。以不变量为准则。没有黑盒。}