crag Anchor

Unit tests for memory. The verified-memory engine for crag: every memory an AI agent saves is decomposed into atomic claims, each claim gets an executable falsifier, and a grounding loop re-verifies them against reality — so recall returns verified facts, not stale notes.

What it is

AI coding agents forget everything between sessions — and worse, when they do have memory, that memory silently rots: ports change, files move, decisions get reversed, and the agent keeps recalling the stale version with full confidence.

crag Anchor treats memory the way engineers treat code: untested memory is broken memory.

• Save — insights captured from agent sessions pass a write-path governance gate (schema checks, secret scan, dedup, lifecycle resolution) before they enter the corpus.

• Decompose — each insight is broken into atomic claims (P1–P5: existence, behavior, causal, spec, meta), and each claim gets an executable predicate — a cheap, read-only check that can prove it wrong.

• Ground — a background worker pool re-runs falsifiers (recall-triggered for hot claims, sweep-based for cold ones). Trust is how recently a claim was re-grounded against reality, not a number that only rises.

• Recall — hybrid semantic + full-text search (embeddings + BM25 + confidence), with a per-hit liveness verdict (fresh / aging / unverified / revalidating / stale) so the agent knows what to discount.

• Govern — contradiction detection, arena adjudication, supersede chains, confidence lifecycle (verify/decay/promote), and a tiered disposition engine (T0 auto / T1 agent / T2 human) for anything an agent proposes to persist.

Architecture at a glance

Claude Code / Cursor session
        │  (stdio)
        ▼
crag-anchor-mcp ──── 30 MCP tools, thin HTTP client, no local state
        │  (HTTP, localhost)
        ▼
crag-anchor daemon ── FastAPI on 127.0.0.1:8786
        │              ├─ embedding model (all-MiniLM-L6-v2, in-RAM)
        │              ├─ claim layer (decompose → classify → author falsifiers)
        │              ├─ grounding workers (v2 queue + v3 LLM adjudication)
        │              ├─ disposition engine (T0/T1/T2 staging triage)
        │              └─ capture pipeline (transcript tailer → extractor → emit)
        ▼
SQLite (WAL) ──────── engine.db: insights, principles, claims, falsifiers,
                      entity graph, grounding history, token ledger

See docs/architecture.md for the honest deep-dive.

The loop

One closed loop turns raw session failures into compiled governance:

capture → disposition (T0 auto / T1 agent / T2 human) → claims → grounding
        → principles → crag distill → .crag/governance.gen.md → crag compile → 23 targets

Trust score is the verified fraction of active claims — only principles whose claims roll up fresh are eligible to compile into governance, so the rules an agent obeys are derived from verified reality, not vibes.

Read-model contract

The daemon exposes ONE read-model; every surface (CLI, console, cloud, ops) renders these same aggregates. No surface owns logic.

Ops-only aggregates (GET /infra/stack, /infra/costs, /infra/sessions) are served exclusively by the private operator instance, appended via the module seam — never present in this open-source engine.

Surfaces

The engine is headless; surfaces render the read-model.

• Embedded console — ONE app, data-driven nav from /console/modules. A module seam lets an operator instance append its infra module without a fork. Embeds via a contract (?embed=1 + postMessage + frame-ancestors from env). (Shipped, live 2026-07-18.)

• crag CLI cockpit — crag status / crag inbox / crag why <id> read the aggregates; crag sync --memory pushes an overview+rules snapshot to app.crag.sh. (On feat/memory-seam; ships in the next @whitehatd/crag release.)

• Cloud — app.crag.sh stores pushed snapshots and renders a "Verified Memory" card. (Deployed.)

Roadmap (honest tense)

Shipped above is live today. In flight and planned:

• P0 — session lifecycle (in progress): session_start / session_end MCP methods + per-harness command hooks (invisible capture/sync, not skills the agent must remember).

• Console v3 (in progress): five decision-surfaces (Memory · Needs You · Browser · Rules · Systems) on the live aggregates, behind a Playwright gate, flipped in via the manifest once they pass.

• P0.5 — BYO-key gateway (planned): bring ANY provider's key — paste-a-key → OS keychain → one provider-neutral gateway with per-role model aliases; spend caps enforced outside agent code. No subscription login (banned by providers in 2026).

• P1 — GitHub App (planned): quiet, evidence-linked PR receipts.

Quickstart

git clone <repo> crag-anchor && cd crag-anchor
python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e '.[embeddings]'

crag-anchor                      # start the daemon (first boot downloads the ~90MB embedding model)
curl -sf http://127.0.0.1:8786/health

# register the MCP server with Claude Code:
claude mcp add --scope user crag-anchor crag-anchor-mcp

Docker, systemd, and launchd paths are documented in packaging/README.md. Zero-config defaults are repo-relative (db/engine.db, logs/, bind 127.0.0.1:8786); everything is overridable via CRAG_ANCHOR_* env vars or db/stack.toml.

Relation to crag

crag (npm i -g @whitehatd/crag) is the deterministic governance compiler: one governance.md source of truth, compiled into every agent format (CLAUDE.md, .cursorrules, AGENTS.md, hooks). crag Anchor is the memory + verification engine underneath it: verified insights distill into principles, and principles whose claims roll up fresh can compile back into governance rules (crag distill). Compiler + engine, one product: rules that are derived from verified reality, not vibes.

MCP surface

30 tools — recall (recall, recall_principle, recall_by_entity), knowledge capture (save_insight, suggest_tags), lifecycle (get, verify, update, supersede, promote_insight), governance queues (audit, arena, clear_suspect, grounding), disposition (disposition_list, disposition_resolve, staging_triage), session state (session_diary, project_context, events, brief), telemetry (recall_stats, recent_insights, cost_report, add_token_record, health_check), governance export (principles_export), and introspection (engine_guide, graph). Full table in packages/mcp-spec/README.md.

Development

pip install -e '.[all]'
ruff check .                                   # lint
python apps/daemon/tests/test_engine_paths.py  # test suites are standalone scripts
python db/tests/test_write_gate.py             # (each exits 0 on pass, 1 on fail)

See CONTRIBUTING.md.

License

Apache-2.0 — see LICENSE and NOTICE. Every line of source in this repository is Apache-2.0 — no carve-outs, no dual licensing, no contributor surprises. Commercial capabilities (hosted console, team memory server, SSO/RBAC, audit export) are delivered as separate distributions built on this engine — see crag.sh.