World Model Mcp

World Model MCP

Persistent memory + optional signed audit for AI coding agents.

world-model-mcp is persistent memory plus a post-quantum-signed, offline-verifiable audit trail for AI coding agents (FIPS 205 hybrid Ed25519 + SLH-DSA), MIT-licensed and fully local.

world-model-mcp ships a local SQLite knowledge graph your agent queries every turn: hallucinations become verifiable, corrections stick across sessions, and regressions get caught before they land. Flip on the audit chain and every event is signed with FIPS 205 hybrid Ed25519 + SLH-DSA, verifiable offline forever. MIT-licensed, runs entirely local, works with 10+ AI coding agents including Claude Code, Cursor, Codex, Continue, Cline, Windsurf, GitHub Copilot Chat, pi, OpenClaw, and Hermes Agent.

Latest: v0.16.2. world-model demo ends with a live notary beat: three sample decisions signed into a real hybrid-signed epoch (Ed25519 + SLH-DSA-SHA2-128f, FIPS 205), verified VALID, mutated one byte to prove tamper detection fires live (INVALID), then restored. Zero signup, zero token, zero network; drops a world-model-demo-receipt.json in the current directory and emits a copy-paste etch.systems/verify#<manifest> URL. v0.16.1 adds a graceful skip when the local liboqs build was compiled without SLH-DSA (rather than crashing the demo). Full version history in CHANGELOG.md.

Try it in 10 seconds

pip install -U world-model-mcp && world-model demo

You will see three sample decisions signed into a tamper-evident epoch, then the demo mutates one byte and re-verifies to prove the tamper is detected instantly (INVALID), then restores and re-verifies (VALID again). Offline, no account, no network. A world-model-demo-receipt.json lands in your current directory and a shareable etch.systems/verify#… URL is printed for anyone to check the same receipt in a browser.

mcp-name: io.github.SaravananJaichandar/world-model-mcp

---

Prefer a managed hosted version?

If you want the same signed audit chain without running the OSS server yourself, etch.systems ships a managed variant that uses this package as its offline reference verifier.

• No infrastructure to run (POST your first event in 30 seconds, no signup)
• Compliance framework mapping to SR 11-7, EU AI Act Article 12, ISO 42001, NIST AI RMF, SOC 2 CC7
• External anchoring shipped end-to-end (Sigstore Rekor + Bitcoin OpenTimestamps)
• Portable per-agent identity with key rotation and delegation across MCP client tools (Claude Code, Cursor, Continue, Cline, Codex)
• Offline verifier stays the same: pip install world-model-mcp && etch-verify manifest.json verifies the hosted chain against pinned public keys without depending on the hosted service being online

curl -X POST https://etch.systems/v1/your-project

Returns a bearer token and an MCP endpoint you can point any MCP-compatible client at. Full docs at etch.systems.

---

FAQ

What is world-model-mcp? world-model-mcp is persistent memory plus a post-quantum-signed, offline-verifiable audit trail for AI coding agents, exposed as an MCP server the agent queries every turn. It runs entirely local, ships as MIT-licensed Python + optional adapters for 10+ AI coding agents.

How is it different from Mem0, Letta, and other agent-memory tools? world-model-mcp is the only agent-memory tool that ships a hybrid post-quantum signed audit chain (FIPS 205 Ed25519 + SLH-DSA-SHA2-128f) alongside memory, with an offline reference verifier (etch-verify) and dual external anchoring (Sigstore Rekor + Bitcoin OpenTimestamps) available via the hosted etch.systems companion. Peer tools (Mem0, Letta, agentmemory) ship memory without a signed audit chain. See the "Compared to" table below for a per-mechanism breakdown.

Is the audit trail post-quantum secure? Yes. Every closed epoch carries a hybrid signature: Ed25519 (classical) plus SLH-DSA-SHA2-128f (FIPS 205 stateless hash-based post-quantum signature). A future quantum adversary that breaks Ed25519 alone still faces the SLH-DSA signature over the same payload; both signatures must forge for the chain to be forged.

How do I verify a record offline, with no account? Run pip install -U world-model-mcp && world-model demo. The demo signs three sample decisions into a real hybrid-signed epoch, exports the same manifest format the etch-verify CLI reads, verifies VALID, mutates one byte to prove tamper detection is live (INVALID), then restores and re-verifies. A world-model-demo-receipt.json lands in your current directory and a etch.systems/verify#… URL is printed for anyone to check the receipt in a browser. Zero signup, zero network.

Which AI coding agents does it work with? Claude Code, Cursor, Codex, Continue, Cline, Windsurf, GitHub Copilot Chat, pi, OpenClaw, and Hermes Agent. Each has a dedicated starter repo under github.com/SaravananJaichandar/world-model-mcp-<agent>-starter. The MCP wire format is standard, so any MCP-capable client can consume the same tools.

Should I use this OSS package or the hosted etch.systems service? Use this OSS package (MIT-licensed, fully local) if you want to run the audit chain on your own infrastructure or add signed memory to an internal tool. Use etch.systems if you want the same audit chain shipped as a managed service with compliance framework mapping (SR 11-7, EU AI Act Article 12, ISO 42001, NIST AI RMF, SOC 2 CC7) and portable per-agent identity across MCP client tools. The offline reference verifier is the same in both cases: pip install world-model-mcp && etch-verify manifest.json verifies either an OSS-generated or a hosted-generated manifest against pinned public keys.

---

Compared to other agent-memory + agent-audit projects

Head-to-head positioning against eight named peers on the audit / signing / anchoring dimensions the agent-memory space is converging on. Every world-model-mcp cell carries a provenance flag: own = measured / observed in the shipped product; cited = pulled from the competitor's own public landing, repo, or press.

Source of truth for this table lives in the hosted service repo: world-model-mcp-hosted/src/etch/competitor_matrix.py. Update in both places if you change either.

	world-model-mcp (this repo) + Etch (hosted)	Mem0	Letta	agentmemory	Unicity AOS	Repowise	Trinitite	Caura	FailproofAI
Signature scheme	Ed25519 + SLH-DSA-SHA2-128f (hybrid) [own]	None (encryption at rest only)	None	None	BLAKE3 hash-chain	Deterministic signals (no signing)	Signed + hash-chained (algo not disclosed)	None	None disclosed
Post-quantum ready	Yes (SLH-DSA, NIST FIPS 205) [own]	No	No	No	No (BLAKE3 hash only)	No	No disclosed	No	No
Offline reference verifier	etch-verify CLI, streaming, ships with PyPI package [own]	No	No	No	Not disclosed	No (SaaS-only)	Browser-based verifier	No	No
Attestation cadence enforcement	Scheduled systemd timer + on-demand verify [own]	No	No	No	Not disclosed	No	Scheduled attestation runs	No	No
Framework mapping (Article / control IDs)	EU AI Act Art. 12-15, SOC 2 CC6.6/7.2/7.3, ISO 27001 A.12.4/A.14.2 [own]	SOC 2 + HIPAA (badges, no per-control mapping)	Not disclosed	No	Not disclosed	EU AI Act (negative-space claim)	Per-Article citations (EU AI Act, SOC 2, SR 11-7)	SOC 2 in-progress badge	SOC 2 enterprise tier only
Drift detection	Per-epoch chain integrity + attestation trend [own]	No	Success-rate + error tracking	No	Not disclosed	Code-health score deltas	Deterministic replay + risk-score deltas	No	Evaluator score deltas
Annotation support (signed human notes in-chain)	pin_annotation MCP tool, signed into same chain [own]	No	No	No	Not disclosed	No	Not disclosed	No	No
Browser verifier	Yes, chain-integrity widget on /auditor/<slug> [own]	No	No	No	Not disclosed	No	Yes	No	No
Share link (auditor access, no login)	Yes, expiring share tokens (bs_ prefix, 30d max) [own]	No	No	No	Not disclosed	No	Yes, expiring auditor access	No	No
External anchor (independent witness log)	Dual: Sigstore Rekor + Bitcoin OpenTimestamps (public, opt-out per project) [own]	No	No	No	Internal hash-chain only (no external log)	No	Not disclosed	No	No
OSS license	MIT (world-model-mcp) [own]	Apache 2.0	Apache 2.0	Apache 2.0	Not disclosed	AGPL v3 (core)	No OSS	Apache 2.0	No OSS
GitHub stars	Snapshot via etch.systems/api/oss-stats [cited]	61.6k [cited]	23.9k [cited]	24.9k [cited]	7.1k [cited]	4.2k [cited]	No public repo	373 [cited]	No public repo
Public funding	Bootstrapped [own]	$24.5M [cited]	$10M [cited]	Not disclosed	$3M seed Feb 2026 [cited]	Not disclosed	Not disclosed	Not disclosed	Not disclosed
Compliance posture (as claimed on landing)	SOC 2 Type I in progress (Aug 2026 target) [own]	SOC 2 + HIPAA (badges on trust subdomain)	Not disclosed	No compliance posture	No compliance posture	No SOC 2; EU AI Act negative-space claim	Per-Article compliance framing	SOC 2 in-progress badge	SOC 2 enterprise-tier

How to read this table:

• Bold cells describe mechanisms shipped in this repo (OSS) or the hosted service (etch.systems).
• Peer cells are cited from each competitor's public landing / repo / press. Not our own measurement.
• [own] on a world-model-mcp cell means we measured / observed the mechanism ourselves. [cited] means the value came from a third-party source.
• Only the audit / signing / anchoring dimensions are in this table. General memory features (retrieval accuracy, adapter breadth, LLM support) are covered in the Features section below.

---

Numbers

Benchmark	Score	Details
SWE-bench Verified repeat-mistake	+10.2 points as a single-trial upper bound (67.3% → 77.6% on 49 paired instances); the multi-seed mean effect is +0.24 per instance, 95% CI [0, 0.47]	Pre-registered, Claude Code 2.1.177 headless, Zenodo DOI 10.5281/zenodo.21076824. Within-domain +15.0 pts, cross-domain +6.9 pts with zero regressions on the single-trial split.
Contradiction-resolution	100.0% on auto strategy	105 pairs × 19 categories, deterministic (no LLM). Shipped since v0.11.0.
Coach-Player verification	100.0% exact match	12 hand-labeled pairs (4 grounded, 4 partial, 4 hallucinated). Layer 3 adversarial verification via independent Coach LLM. Shipped since v0.12.12.

The SWE-bench number is the load-bearing empirical claim. The other two are internal correctness benchmarks for shipped components. Reproducibility scripts in each benchmark directory or the linked repo.

---

Testing

1,494 unit + integration + fuzz tests across the shipped codebase. Coverage floor gated at 71% / 66% (two-tier for CI runners with and without SLH-DSA in liboqs).

# Run tests
pytest -q

# With coverage
pytest --cov=world_model_server --cov-report=term-missing

# Fuzz targets (Atheris, requires Clang / libFuzzer)
python fuzz/fuzz_verify_manifest.py fuzz/corpus/ -max_total_time=60

# Non-Atheris smoke fuzz (runs in every CI pass, no system deps)
pytest tests/test_fuzz_smoke_verify.py -q

Selected test suites worth calling out:

• FIPS 205 SLH-DSA known-answer tests (tests/test_fips_205_slh_dsa_kat.py): locks parameter sizes for SLH-DSA-SHA2-128f (public key = 32 bytes, secret key = 64 bytes, signature = 17,088 bytes), sign/verify round-trip with wrong-key + wrong-message + mutated-signature rejection, plus a fixed KAT-vector fixture (tests/fixtures/slh_dsa_kat_vectors.json) that must verify true forever.
• Streaming verifier byte-parity (tests/test_etch_verify_streaming.py): locks byte-identical output between in-memory and streaming exporters so an auditor hashing the manifest as an artifact of record gets the same manifest_sha256 regardless of which exporter the operator used.
• Contradiction benchmark (benchmarks/contradictions-200/): 105 pairs × 19 categories, deterministic. Locks the auto strategy at 100% on every commit.

CI gates coverage floor + full test suite on every push. See .github/workflows/pytest.yml.

---

Authenticated audit chain (v0.13+, opt-in)

For deployments where the audit trail must be cryptographically verifiable (SOC 2, HIPAA, EU AI Act, or your own internal control list):

export WORLD_MODEL_AUDIT_LOG=on
# then start the world-model-mcp server as normal

On the first opt-in start, the server creates two new SQLite tables in the existing audit.db file (tamper_evident_log and tamper_evident_epochs) and generates a new hybrid keypair on the first epoch close. Every subsequent event is appended to a SHA-256 Merkle chain. When an epoch closes (default: 1024 events), the chain root gets signed with a hybrid Ed25519 + SLH-DSA-SHA2-128f envelope: classical + post-quantum, so a hypothetical break of elliptic-curve cryptography leaves the audit trail intact.

• Verifiable offline, forever. etch-verify CLI ships with the PyPI package; auditors run it on their laptop, no network access needed after the initial download.
• Signatures prove authorship, not just order. Hash-chain alternatives can prove nothing was reordered, but cannot prove WHO signed. This chain answers both.
• No dashboard, no signup, no external service. Runs entirely in your process against local SQLite.

Full write-up in docs/AUDIT_LOG.md.

For a hosted version that adds KMS-backed keys, a public transparency log, external anchoring to Sigstore Rekor + Bitcoin OpenTimestamps, and a compliance-facing operator dashboard, see the Etch companion below.

---

Quick Start

Three most-common install paths. For every other supported client (Cursor, Cline, Codex, Continue, Copilot, Windsurf, Goose, pi, OpenClaw, Hermes, and more), see etch.systems/docs/install.

Option 1: Claude Desktop (one-click)

Download the latest .mcpb from Releases and drag it into Claude Desktop. Auto-installs hooks, MCP server config, and dependencies.

Option 2: Claude Code / IDE plugins (pip install)

# 1. Install the package
pip install world-model-mcp

# 2. Set up in your project (auto-seeds the knowledge graph from existing code)
cd /path/to/your/project
python -m world_model_server.cli setup

# 3. Restart Claude Code
# Done. The world model is pre-populated and active.

Next (optional): turn the local signed audit log into an auditor-verifiable chain with the hosted Etch notary — KMS-backed keys, public transparency log, external anchoring, and a share link for auditors, with no infra to run. See Hosted companion: Etch.

Option 3: HTTP transport for remote / MCP-tunnel deployment

pip install 'world-model-mcp[http]'
python -m world_model_server.server --transport http --port 8000

Exposes MCP over Streamable HTTP so remote agents can connect over the wire. See docs/http_transport.md for auth, CORS, and reverse-proxy setup.

Other clients

Install via the OSS CLI. Each command writes the correct config for that client (defaults to sys.executable as the interpreter path, per-client-format-aware, safe against overwrite via --force and --dry-run flags):

python -m world_model_server.cli install-cursor     # Cursor
python -m world_model_server.cli install-cline      # Cline
python -m world_model_server.cli install-codex      # Codex
python -m world_model_server.cli install-continue   # Continue (also --global)
python -m world_model_server.cli install-copilot    # GitHub Copilot Chat (VS Code Insider)
python -m world_model_server.cli install-windsurf   # Windsurf
python -m world_model_server.cli install-pi         # pi
python -m world_model_server.cli install-openclaw   # OpenClaw
python -m world_model_server.cli install-hermes     # Hermes (MCP mode)
python -m world_model_server.cli install-hermes-provider  # Hermes (Elixir-native provider)

Full per-client walkthroughs (with verify commands + troubleshooting) at etch.systems/docs/install.

---

What it does

world-model-mcp is a temporal knowledge graph that sits between your AI coding agent and its work. It records facts, entities, and constraints from your codebase; validates every code change against learned constraints at the edit boundary; re-injects relevant context after context-window compaction; tracks contradictions with confidence-weighted resolution; and adversarially verifies retrievals via an independent Coach LLM.

Features

1. Hallucination prevention. Every fact recorded carries provenance (asserted_by, confirmer, confirmation_state, evidence_type). When the agent queries a fact, it gets the confidence score along with the answer. When two facts contradict, the newer/higher-confidence one wins; the loser is retained with superseded_by. The agent never has to guess whether a stored fact is still current.

2. Learning from corrections. When you correct an agent (record_correction), the correction is stored as a first-class event with the entities involved. Next time the agent queries anything touching those entities, the correction surfaces first. Corrections stick across sessions, across context compactions, across agent restarts.

3. Regression prevention. Every code-change proposal runs through validate_change, which walks the constraint graph and returns violations before the edit lands. Constraints are learned automatically from your codebase (seed_project), reinforced by PR review comments (ingest_pr_reviews), and hand-authored (record_event). The agent sees the violation, the suggestion, and the source of the constraint.

4. Coach-Player adversarial verification. A Player agent drafts a decision. An independent Coach agent independently requeries the graph for precedent, walks the Merkle proof, checks the hybrid signature, and only then approves. The Coach never trusts the Player's summary; it reverifies against a signed ledger every time. 100% exact match on 12 hand-labeled pairs.

Full technical architecture in docs/ARCHITECTURE.md.

---

MCP Tools

Eight tools shipped. One-line summary; click each for signature + examples in docs/mcp/.

Tool	What it does
query_fact	Fetch a stored fact with provenance + confidence + source
record_event	Append an event to the audit chain (event_type from a fixed enum)
validate_change	Check a code-change proposal against learned constraints, returns violations + suggestions
get_constraints	List all constraints matching an entity or file pattern
record_correction	Store a user correction so it re-surfaces on next relevant query
get_related_bugs	Fetch bugs touching the given files + a per-file risk score
seed_project	Bulk-ingest an existing codebase into the knowledge graph
ingest_pr_reviews	Turn recent PR review comments into constraints

Full tool documentation at docs/mcp/.

---

Hosted companion: Etch

Running world-model-mcp locally? Etch (etch.systems) is the hosted governance plane built on the same OSS core, adding what a compliance team needs to sign off on production use:

• KMS-encrypted signing keys (never plaintext at rest)
• Public transparency log with signed head (split-view resistance)
• External anchoring to Sigstore Rekor + Bitcoin OpenTimestamps (dual independent witness)
• Operator dashboard with session traces, chain integrity view, PII scanning, and a client-answer PDF export
• Standalone auditor CLI + browser verifier at /auditor/<slug>
• Free tier, pay-as-you-grow beyond that

Same crypto primitives, same audit-log schema, zero source changes to the shipped OSS. Skip if you're running standalone.

Which one is right for me?

Situation	Route
I want persistent memory for my local AI coding agent	world-model-mcp (this repo, MIT)
I want to prove agent decisions to a regulator six months later	etch.systems
I want signed evidence bundles a court can self-authenticate	etch.systems
I want cross-team or cross-vendor federation of signed audit history	etch.systems
I want to try both	Start local with world-model-mcp; add Etch when you need signed evidence for someone else to verify

---

How it works

world-model-mcp is an MCP server (stdio or Streamable HTTP) that exposes a temporal knowledge graph backed by SQLite. Every agent turn queries the graph; every code change or correction writes back. On startup the server auto-seeds from your existing codebase; on shutdown it flushes cleanly.

Six databases under .claude/world-model/:

• entities.db: files, functions, classes, symbols
• facts.db: semantic facts with provenance + confidence
• relationships.db: dependencies, calls, imports
• constraints.db: learned rules the agent must respect
• sessions.db: per-session context tracking
• events.db: immutable event log (audit chain when opted in)

Full architecture with diagrams in docs/ARCHITECTURE.md.

---

Configuration

Environment variables (all optional):

Variable	Purpose	Default
WORLD_MODEL_AUDIT_LOG	Enable the signed audit chain	off
WORLD_MODEL_DB_PATH	Override the SQLite databases directory	.claude/world-model
WORLD_MODEL_TELEMETRY	Opt in to anonymous OSS telemetry (see Privacy)	off
ANTHROPIC_API_KEY	Only used if you enable optional LLM-backed features	none

Full configuration reference in docs/CONFIGURATION.md.

---

Privacy and Security

• Telemetry is off by default. If you opt in with WORLD_MODEL_TELEMETRY=on, aggregated install-level metrics ship to etch.systems/api/telemetry/ingest (endpoint URL, no source code, no prompts, no PII). Right-to-erasure supported via DELETE /api/telemetry/install/{install_id}.
• No ANTHROPIC_API_KEY is required for core operation. Some optional features (Coach-Player Layer 3 verification, LLM-backed reranking) use the API if a key is provided. Without it, everything else works.
• Report a security issue: email security@etch.systems. PGP key on request.

Full write-up in docs/PRIVACY.md.

---

Contributing

Contributions are welcome. See CONTRIBUTING.md for development setup, coding standards, adding language support, writing tests, and submitting PRs.

Areas where help is especially wanted:

• Language parsers (Go, Rust, Java, C++)
• Additional MCP-client adapters
• Framework integrations (LangGraph, CrewAI, AutoGen, LlamaIndex; starter shims exist in the hosted repo)
• Benchmark contributions in benchmarks/

Please read CLA.md before your first PR.

---

License

MIT License. Free for commercial and personal use.

---

Links

• Full version history: CHANGELOG.md
• Documentation: docs/
• Hosted service: etch.systems
• Benchmarks: benchmarks/ + coding-agent-memory-benchmark
• Support: support@etch.systems
• Zenodo (formal citation): DOI 10.5281/zenodo.20834508