LoopForge

A context window is not memory. Memory needs a runtime.

v2.11.0 — npm install -g loopforge. Node.js ≥ 18. Zero runtime dependencies. 中文文档

---

The real problems with long-horizon tasks

Any AI coding agent, given a long enough task, hits three walls. Not because the model isn't smart enough. Not because the context window isn't large enough. These are architectural problems.

Problem 1: The summary cascade

Context fills up → compress. Fills up again → compress again. The third compression is a summary of a summary of a summary. Every cycle evaporates information — critical constraints get silently deleted because the summarizer judged them "no longer relevant." Researchers found that after 3–4 summary cycles, constraint violation rates spike from 0% to 59%. The agent doesn't know what it forgot, because the forgetting itself was compressed away.

This is what happens when you treat cognitive state as context. The bucket always leaks.

Problem 2: Self-correction doesn't work

Google DeepMind's conclusion is clear: models cannot reliably improve themselves through introspection. They talk themselves out of correct answers. Effective recovery requires an external verifier — an independent observer that doesn't share the agent's context, doesn't participate in its reasoning, and only looks at inputs and outputs. The verifier must never be the same context that made the mistake.

Problem 3: Compound error (p^N)

If each step succeeds with probability p, N sequential steps succeed with probability p^N. METR found that frontier agents nail nearly 100% of tasks a human finishes in under 4 minutes, then crater to under 10% on tasks taking more than 4 hours. Small errors at each step become the correct input for the next step. The agent builds on errors, each step looking locally reasonable, while the entire trajectory is fiction.

These three problems amplify each other. The summary cascade loses information → lost information becomes errors → the agent can't self-correct because those errors look reasonable within its own context.

---

What LoopForge does about it

LoopForge runs outside the agent. It provides a typed vault that survives context compression, an external verification-and-enforcement pipeline the agent cannot self-provide, and a recovery system that walks back from dead ends without human intervention.

1. Vault → compile, not summary → summary

Each round's self-evaluation is written to a typed JSON vault. The next round's prompt is not a compressed version of the previous prompt — it's recompiled from the vault. Milestones are recomputed from raw vault entries, not chained from prior summaries. Constraints, criteria, and sub-goals carry stable hash-derived IDs (c- / cr- / sg-XXXXXXXX) for exact matching across rounds. Delete the state file and it regenerates from the vault.

❌ Traditional: prompt → summary → next prompt → re-summarize → …
✅ LoopForge:  prompt → vault entry → next prompt (recompiled from vault)

2. External verification & enforcement

The verification gate (11 cross-checks) compares every agent claim against independent evidence — Git snapshots, test runner output, explicit verification commands. The enforcement gate (7 rules) decides what to do. Its focus is not "did the agent violate constraint X" — it detects what the agent cannot self-diagnose:

• R1: Claimed success but criteria remain unmet → self-deception
• R3: Claimed success with no verifiable evidence → empty claim
• R4: Flat progress for 3 rounds → stalled without knowing it
• R5: Zero forward motion → going through the motions
• R7: Said X, did Y → intent and actions disconnected

The agent is the system that produced those narratives. It cannot detect these patterns from the inside.

3. Recovery: reject, backtrack, resume

Zero-commit rejection — a rejected round writes nothing to the vault. The round ID stays stable, the attempt counter increments, and the next prompt includes a diagnostic gap showing exactly what didn't match.

Backtrack — when progress stalls (R4/R5), the loop rolls back to the last clean round instead of terminating. A diagnosis of why the path failed is injected. The backtrack prompt includes workspace restore commands with affected file lists; the next submission is rejected if the workspace wasn't restored. Valid discoveries from skipped rounds are preserved.

Pause / Resume / Replay — cross-process session leases. Idempotent resume after interruption. Time-travel queries over committed rounds.

---

What LoopForge is not

• ❌ Not a memory system — the state file is a derived view. The vault is truth. No RAG, no vector DB.
• ❌ Not a context compressor — doesn't compress prompts or do smart summarization. Recompiles from vault, not from the previous prompt.
• ❌ Not a constraint tracker — constraints are one signal the verification gate monitors. The core value is external judgment.
• ❌ Not a replacement for the agent — the agent still reads code, edits files, runs tools, and decides how to reason. LoopForge owns the round boundary.

---

Install

npm install -g loopforge
loopforge init --client claude
claude mcp add loopforge -- npx loopforge mcp

Works with Claude Code, Codex CLI, or any MCP-compatible client.

The MCP server path (loopforge mcp) is the primary integration. It provides the full cognitive infrastructure: verification gate, enforcement gate, backtrack, evidence collection, and crash recovery. The engine is also available as a library for custom integrations — see the API reference.

---

Architecture

┌─────────────────────────────────────────────────────┐
│                  Agent executes round                 │
│  Reads code · Edits files · Runs tools · Reasons      │
└──────────────────────┬──────────────────────────────┘
                       │ Agent submits SelfEvaluation
                       ▼
┌─────────────────────────────────────────────────────┐
│               LoopForge round boundary                │
│                                                       │
│  Evidence → Verify → Enforce → Commit → Compile       │
│  (Git/cmd) (11 checks) (7 rules) (vault)  (next)     │
│                                                       │
│  accept:    commit state, compile next round           │
│  reject:    retry same round, zero state mutation      │
│  backtrack: roll back, restore workspace, inject diag  │
│  terminate: persist terminal state                     │
└──────────────────────┬──────────────────────────────┘
                       │ Recompile prompt from vault
                       ▼
┌─────────────────────────────────────────────────────┐
│             Vault (typed JSON persistence)            │
│  loops/<id>/rounds/<n>.json · session.json · policy   │
│  Source of truth. Not a summary chain.                 │
└─────────────────────────────────────────────────────┘

---

Core capabilities

Durable cognitive state

Every round's self-evaluation is written to the vault. The next prompt is recompiled from vault entries — milestones aren't "summaries of summaries," sub-goal states aren't "compressed then compressed again." Stable IDs (c- / cr- / sg-XXXXXXXX) enable exact matching of constraints, criteria, and sub-goals across rounds — no Jaccard false positives.

The compiler tracks sub-goals through a five-state lifecycle (pending → in_progress → done / blocked / canceled), manages constraint decay (discovered constraints demote to inactive after prolonged irrelevance, then auto-reactivate on violation), and builds hierarchical summaries with phase-boundary milestones that survive rolling-window eviction.

External verification & enforcement

The verification gate runs 11 cross-checks against independent evidence: progress regression, empty-change-with-passing, success-with-remaining-criteria, duplicate constraint discovery, recurring violations, retract-fresh-constraint, evidence integrity (Git), required command evidence, command evidence mismatch, intent-action drift, and sub-goal drift.

The enforcement gate's 7 rules detect cognitive integrity failures: fake success (R1), recurring violations (R2), empty success (R3), progress stall (R4), terminal flatline (R5), max rejections (R6), and intent drift (R7). R7 accepts intentional pivots only when the drift clarification references concrete IDs or file paths — three consecutive weak clarifications without anchors terminate the loop.

Recovery

Rejected rounds commit nothing. Stalled progress triggers backtrack to the last clean round with a diagnosis injected. The backtrack prompt includes workspace restore instructions; the next submission is verified for workspace cleanliness. Sessions survive process restarts via renewable cross-process leases — resume picks up exactly where you left off.

Agent autonomy

L0 (retry) / L1 (continuation) / L2 (full rehydration) control state density only — reasoning strategy belongs to the agent. Each round, the agent can express information needs via prompt_requests (emphasize, expand, confusion_points). The compiler reorders the prompt within safety boundaries; mandatory sections are never removed.

Nine MCP tools (start · next · status · stop · pause · list · replay · resume · health) with typed structuredContent. Zero runtime dependencies — Node.js stdlib only. All thresholds, budgets, and intervals live in loop_policy.json. 491 tests.

---

License

MIT