Korg Recall MCP

korg

A tamper-evident, SHA-256-chained ledger for AI agents. *Every step your agent takes is recorded in a hash chain anyone can verify — edit one event and the chain names it. No trust in the producer, no blockchain.*

English · 简体中文 · 繁體中文

---

30-second quickstart

Build the standalone verifier (~10s cold — it compiles only the ledger crates), verify a recorded Claude Code session, then rewrite one event and watch the chain catch it:

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)

No Rust toolchain? Drop the same file into the in-browser verifier — it runs locally and sends nothing.

---

Validated across three vendors (N=3)

The same korg-ledger@v1 format ingests traces from three architecturally different production agents, with causal structure (spec §2a) preserved through the round-trip:

Because all three land in one format, one verifier checks them all — and it has byte-identical Rust, Python and JS implementations, differentially fuzzed against each other with 0 divergences. Known limits are written down rather than hidden: see the Grok Heavy limitations (ingest order vs. wall-clock concurrency, cross-agent chatroom edges).

---

Full demo: record → verify → rewind

---

AI agents are black boxes. When they fail, you can't debug. When they succeed, you can't reproduce it.

When they do something wrong, you can't undo it.

Korg fixes this.

---

What Korg Does

[!NOTE]

Universal Ingestion Integration Mode:

Korg v1 is an MCP-callable audit sink. Any MCP-compatible coding agent (Claude Code, Codex, etc.) can call korg's tools to record its session as a causally-linked, replayable, rewindable ledger. The agent must be instructed to log its actions — typically via system prompt or MCP server configuration. Fully passive auditing without agent cooperation is on the roadmap for future versions.

[!WARNING]

Trust Boundary & Deployment Scope:

Korg v1 is designed strictly for local, single-user workspaces. Multi-tenant and networked deployments require cryptographic authentication and permission bounds that are not yet shipped. Running the server on an untrusted or public network exposes workspace read/write access.

Korg is a cognitive hypervisor — a runtime layer that sits beneath your AI agents and governs every decision they make.

It doesn't replace your LLM. It governs what the LLM does.

Foundation Model          →  predicts, suggests, generates

──────────────────────────────────────────────────────────── Korg Cognitive Runtime → schedules, validates, isolates, reconciles, replays, heals, governs

Every agent action is:

• Appended to an immutable, cryptographically-signed ledger
• Ordered with Hybrid Logical Clocks (causal, deterministic, globally consistent)
• Replayable — rebuild exact state at any point in history
• Reversible — rewind the ledger to any prior sequence point

---

Try the Time-Travel Demo

You can run the built-in sandbox demo to see cognitive time-travel in action. The demo sets up a temporary workspace with a buggy Python script, lets a simulated coding agent make a wrong edit, catches the test failure, rewinds the workspace and ledger to before the edit, and speculatively commits the correct fix:

cargo run -- demo

You will see the complete, colorized time-travel sequence:

⚡ 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:claude-code@0.2.29 | tool: user_prompt | prompt: "Fix subtraction bug and verify tests pass" [seq 391] actor: agent:claude-code@0.2.29 | tool: Read | file: math_utils.py [seq 392] actor: agent:claude-code@0.2.29 | tool: Edit | result: "Modified return a + b (wrong fix)" [seq 393] actor: agent:claude-code@0.2.29 | 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:claude-code@0.2.29 | tool: Edit | result: "Modified return a - b (correct fix)" [seq 393] actor: agent:claude-code@0.2.29 | 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.

*No other AI agent runtime lets you do this.*

---

Core Architecture

Korg is built on the same theoretical foundations that make databases and operating systems reliable — applied to AI cognition for the first time.

┌────────────────────────────────────────────────────────────────┐

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

---

Quick Start

Build from source

The crate is not yet published to crates.io; install from source:

git clone https://github.com/New1Direction/korg

cd korg cargo build --release ./target/release/korg --help

Python bridge (for 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)"

Run your first campaign

# 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 & Verify

# 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) \\\"