World Model MCP

Enforcement, provenance, and harness-neutral memory for AI coding agents. A temporal knowledge graph that validates code changes against learned constraints at the edit boundary, re-injects relevant context after compaction, tracks contradictions with confidence-weighted resolution, and runs across Claude Code, Cursor, Codex, pi, OpenClaw, Hermes Agent, and Continue.

Status: v0.11.0 — 27 MCP tools, 23 CLI subcommands, 457 tests, SWE-bench Verified repeat-mistake benchmark with a pre-registered methodology and a multi-seed replication appendix, plus a v0.8.1 contradiction-resolution benchmark now at 100.0% on the auto strategy (up from 77.1% in v0.10). v0.11.0 is a depth release. v0.10 (2026-07-01) extended the harness-neutral memory story from four runtimes to seven with the OpenClaw / Hermes / Continue adapters; v0.11.0 (2026-07-02) solves real problems for the users we now have rather than adding more runtimes. Four things ship: (A) auto contradiction-resolution strategy rewrite — folds in confirmer awareness, per-evidence-type decay, distinct-source-tool counting, and tie-detection; benchmark jumps from 77.1% to 100.0% on the same 105-pair × 19-category dataset. (B) Hermes native MemoryProvider plugin — intercepts writes at Hermes' routing layer rather than only surfacing tools, closing the architectural gap the v0.10 MCP adapter could not, motivated by Hermes #47349. (C) content-type routing schema field (rule / fact / procedure) — nullable and additive, enables MemoryProvider implementations to route writes by content shape, not just by tool call. (D) dogfooding case study — publishes what the fact graph captured about the world-model-mcp codebase itself (3 learned constraints with real violation counts, 1 real bug_fix reflection, 608 facts, 600 entities) AND what it did not capture (empty events / decisions / sessions tables). Pushing on that anomaly surfaced the actual root cause: setup_command wrote unquoted $CLAUDE_PROJECT_DIR in every generated hook command, so any user whose project path contains a space silently got zero hook captures. The bug was shipped since v0.7.3; the fix ships in this release with a regression test. Reproducibility contract: python scripts/dogfooding_snapshot.py regenerates the cited numbers byte-for-byte from the shipped DB. v0.10.1 was a doc-honesty patch (stale Zenodo DOI reference corrected). v0.9.2 shipped the multi-seed replication appendix per pre-registered SEED_PLAN.md: on the 17-instance subset, load-bearing replication count is 0 of 7, mean paired delta across two seeds is +0.24 per instance with bootstrap 95 percent CI [0.00, 0.47]. The v0.9 +10.2 pts headline reads as a single-trial upper bound; the wedge claims (lifecycle-hook capture, per-fact provenance, per-evidence-type decay, PreToolUse defer) survive the multi-seed update because they are architectural, not empirical. Full appendix and per-instance results in benchmarks/repeat-mistake/RESULTS.md. v0.9.1 restored the embedded telemetry token after a release-mechanics miss in v0.9.0. v0.9.0 shipped the empirical wedge proof. v0.8.1 expanded the contradiction-resolution benchmark to 105 pairs across 19 categories. v0.8.0 added domain-aware confidence decay with per-evidence-type TTL, per-item provenance fields source_tool and confirmer, slash command write operations, and a confirmer parameter on resolve_contradiction. Antigravity adapter held pending a TransformCompactionHook in the SDK. v0.7.6 added the /world-model slash command and status-watch TUI widget. v0.7.5 added the Codex CLI adapter. v0.7.0 introduced PostCompact auto-injection, the defer enforcement tier, confidence-weighted contradiction resolution, and a compaction audit log. Contributions welcome.

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

If world-model-mcp helped you, star the repo or open an issue with what worked or didn't. I read every one and the feedback shapes what ships next.

What It Does

World Model MCP creates a temporal knowledge graph of your codebase that learns from every coding session to:

• Prevent Hallucinations -- Validates API/function references against known entities before use
• Stop Repeated Mistakes -- Learns constraints from corrections, applies them in future sessions
• Reduce Regressions -- Tracks bug fixes and warns when changes touch critical regions
• Survive Compaction -- Re-injects top constraints and recent facts after the agent's context window resets
• Resolve Contradictions -- Picks a winner between conflicting facts using confidence, recency, or source count

Think of it as a long-term memory layer that runs alongside Claude Code, Cursor, Codex, pi, OpenClaw, Hermes Agent, Continue, or any MCP-aware coding agent.

What's new in v0.11.0

• auto contradiction-resolution strategy rewrite (v0.11.0 A). Folds in confirmer awareness, per-evidence-type decay, distinct-source-tool counting, and tie-detection. Lifts the v0.8.1 contradiction-resolution benchmark's auto score from 77.1% → 100.0% on the same 105-pair × 19-category dataset. Overall benchmark accuracy across four canonical strategies + the decayed strategy rises from 78.2% to 83.7%. Non-auto strategies unchanged. The keep_higher_confidence_decayed strategy is promoted from benchmark-only to a first-class option in pick_winner. Full detail in benchmarks/contradictions-200/.

• Hermes native MemoryProvider plugin + install-hermes-provider CLI (v0.11.0 B). Python plugin implementing Hermes' agent/memory_provider.py ABC (initialize, get_tool_schemas, handle_tool_call, get_config_schema, save_config). Intercepts writes at Hermes' routing layer rather than only surfacing tools — the architectural distinction the v0.10 MCP adapter could not close. Motivated by the Hermes #47349 exchange where @TechFlipsi surfaced that adding another MCP-registered store doesn't fix "the agent still defaults to writing MEMORY.md" — only a MemoryProvider does. Ships as world_model_server/hermes_memory_provider/ in the wheel; install-hermes-provider copies the plugin to <hermes_home>/plugins/memory/world-model/. Seven surfaced tools (query_fact, get_constraints, get_injection_context, record_event, record_correction, find_contradictions, resolve_contradiction) — trimmed from the 27 exposed via MCP to keep Hermes' tool namespace focused. Optional Hermes lifecycle hooks (sync_turn, on_pre_compress, prefetch, on_session_end) tracked as v0.12.

• Content-type routing schema field (v0.11.1). Nullable content_type: Optional[Literal["rule", "fact", "procedure"]] on the Fact model and the facts table. Additive-only migration; existing rows keep NULL and continue to work. Distinct from evidence_type (which describes where the fact came from) — content_type describes what shape of content the fact carries, so a MemoryProvider can route writes intelligently (rules → always-inject, facts → search-on-demand, procedures → skills store) instead of dumping everything into one destination. Sourced from the Hermes #47349 architectural framing. Consumers (query filters, MemoryProvider write routing) are v0.11.x follow-ups; this ships the schema, tests, and migration only.

• Dogfooding case study (v0.11.2) — surfaced a real shipped bug that was fixed in the same release. Publishes what the fact graph actually captured about the world-model-mcp codebase in .claude/world-model/: 3 learned constraints with real violation counts (including check-twine-before-tag and tag-before-upload, both derived from real release-mechanics incidents matching the v0.9.1 telemetry-token miss and the v0.10.1 tagging lesson), 1 bug_fix reflection citing a real bug in world_model_server/knowledge_graph.py:120-135, 608 facts (607 from the seeder + the one bug_fix), 600 entities. Honest about what was NOT captured (empty events / decisions / sessions tables). Pushing on that anomaly hard enough surfaced the actual root cause: setup_command wrote unquoted $CLAUDE_PROJECT_DIR in every generated hook command, so any user whose project path contains a space (macOS defaults like ~/Documents/, corporate paths, or the maintainer's own claude context graph/world-model-mcp) has been silently failing every hook invocation since v0.7.3 shipped hooks. The fix ships in this release — two-line shell-quoting change in setup_command + regression test. This is the exact kind of latent bug that dogfooding is supposed to catch, and it did. Reproducibility contract: python scripts/dogfooding_snapshot.py --db-path .claude/world-model regenerates the committed JSON byte-for-byte, and drift-protection tests fail if the writeup and the snapshot diverge. See case-studies/v011-dogfooding/.

• What is unchanged. All v0.10.x code paths: the 27 MCP tools reported by adapters (no new server-side tools in v0.11), the SWE-bench Verified benchmark and its multi-seed appendix, the seven-runtime adapter coverage (Claude Code + Cursor + Codex + pi + OpenClaw + Hermes Agent + Continue), the Zenodo preprint (paper unchanged since v0.9.2; no new Zenodo version). v0.11 is a depth release — better contradiction-resolution intelligence, a second Hermes integration path, a schema axis for future routing work, and honest evidence for the dogfooding claim. Test count grew from 417 (v0.10) to 457 (+21 for the Hermes MemoryProvider plugin, +10 for the content-type schema, +9 for the case-study drift protection).

What's new in v0.10.0

• Three new adapters in one release: OpenClaw, Hermes Agent, Continue. All three verified end-to-end against real installations of the target runtime:

  • OpenClaw — install-openclaw merges into ~/.openclaw/openclaw.json. Verified against OpenClaw 2026.6.11 (e085fa1) on macOS: openclaw mcp probe world-model reports 27 tools discovered. Root cause of the first-attempt "MCP error -32000: Connection closed" surfaced and fixed during E2E: OpenClaw's process spawn does not inherit shell PATH, so --command python3 fails while an absolute path works. The CLI now defaults command to sys.executable (absolute) and rejects relative --python overrides as a hard error. Documented as an install-time gotcha in the adapter README.
  • Hermes Agent — install-hermes merges into ~/.hermes/config.yaml under mcp_servers.world-model. Uses ruamel.yaml round-trip mode to preserve every comment and blank line in Hermes' heavily-commented 1327-line reference config. A regression test (test_f2_install_hermes_preserves_comments_and_blank_lines) locks this down after a pre-E2E pyyaml.safe_dump implementation stripped ~1170 lines of documentation. Verified against Hermes Agent v0.17.0 (2026.6.19) on macOS: hermes mcp test world-model reports 27 tools discovered. Hermes' built-in memory (character-capped, no auto-decay per Hermes docs) is complemented additively by world-model-mcp's provenance + decay schema. Requires the [hermes] optional extra (pip install "world-model-mcp[hermes]") so ruamel.yaml is available.
  • Continue — install-continue writes a standalone <project>/.continue/mcpServers/world-model.yaml following Continue's documented per-server-file pattern. No config merge needed. CLI-side E2E: the exact stdio spawn Continue would perform returns 27 tools via a live tools/list roundtrip. Last-mile "does Continue's LLM see them in agent mode" verification requires a live VS Code / JetBrains session. Reprioritized after the SpaceX/Cursor acquisition to serve teams standardizing on OSS-neutral coding-agent workflows.

• Absolute-path posture across all v0.10 adapters. OpenClaw's PATH-spawn issue was caught first, but the same absolute-path default applies to Hermes and Continue as a precaution. Every new install command defaults command to sys.executable and rejects relative --python overrides. Users who hand-edit config files are directed to $(which python3) in both READMEs.

• Cross-runtime shared memory. All v0.10 adapters (and every prior adapter) default WORLD_MODEL_DB_PATH to .claude/world-model — a relative path resolved against the client's working directory. This means a project that runs in multiple clients (e.g., Claude Code + Continue + OpenClaw) shares one SQLite fact graph across all of them. For user-wide shared memory regardless of CWD, override with an absolute --db-path. The differentiator against ClawMem (which does cross-runtime memory with a plain key-value SQLite vault) is depth: per-fact provenance, per-evidence-type decay half-lives, PreToolUse defer enforcement.

• What is unchanged. All v0.9.2 code paths: the 26 base MCP tools (v0.10 adds no new server-side tools; the "27 tools" count reported by adapters includes resolve_contradiction which shipped in v0.8.0), the SWE-bench Verified benchmark, the multi-seed replication appendix, the wedge claims. v0.10 is an adapter-surface release, not a schema-or-benchmark release. Test count grew from 375 (v0.9.2) to 417 with the three new adapter test suites; every baseline test still passes.

• Test breakdown. 375 baseline + 14 OpenClaw + 16 Hermes + 12 Continue = 417 tests. Every adapter's test suite includes: bundled-file validity, dry-run behavior, first-install writes with absolute-path defaults, idempotence (refuse to overwrite without --force), --force overwrite, relative---python rejection, parent-directory creation, malformed-config-file handling, and subparser-registration regression coverage.

What's new in v0.9.2

• Multi-seed replication appendix shipped per SEED_PLAN.md. The v0.9 paper's primary limitation was single-trial design. v0.9.2 ships the multi-seed test that SEED_PLAN.md (locked 2026-06-25) committed to running. The result is published verbatim per the pre-registered acceptance criteria.

• Honest update to the v0.9 headline. On the 17-instance pre-registered subset, baseline pass rate swung +41 percentage points between seed 1 and seed 2 with no methodology change. Load-bearing replication is 0 of 7 instances. Mean paired delta across both seeds is +0.24 per instance with bootstrap 95 percent CI [0.00, 0.47]. The v0.9 +10.2 pts paired delta should be read as a single-trial upper bound; the replicated effect size is small, possibly nonzero.

• What is unchanged: all v0.9.1 code, the 26 MCP tools, the 19 CLI subcommands, the 375 tests, the wedge claims at the architectural level (lifecycle-hook capture, per-fact provenance, per-evidence-type decay, PreToolUse defer). Architectural claims do not depend on the empirical effect size and survive the multi-seed update.

• Documentation diffs: benchmarks/repeat-mistake/RESULTS.md adds a "Multi-seed replication appendix (v0.9.2 update)". benchmarks/repeat-mistake/paper.md adds Appendix A with the same content. benchmarks/repeat-mistake/paper.pdf is regenerated. benchmarks/repeat-mistake/SEED_PLAN.md adds a status update (the locked plan above is unchanged). Raw seed-2 artifacts (baseline_progress_seed2.jsonl, treatment_progress_seed2_treatment.jsonl, predictions, results, and the multi_seed_summary_seed2.json from multi_seed_aggregate.py) committed.

• The methodology discipline held. Pre-registration prevented goalpost-moving. The honest update is published per the locked SEED_PLAN.md acceptance criteria. This is what pre-registration is for.

What's new in v0.9.0

• Repeat-mistake benchmark on SWE-bench Verified — the central wedge proof. 50 SWE-bench Verified tasks across django, sympy, matplotlib, scikit-learn, and sphinx, run as a paired baseline-vs-treatment comparison. Methodology was locked at benchmarks/repeat-mistake/DESIGN.md on 2026-06-17 (before the data existed) so the result cannot be accused of goalpost-moving.

• Headline results — Subset 1 (within-domain: django + sympy) baseline 15/20 = 75.0 percent, treatment 18/20 = 90.0 percent, delta +15.0 pts with 4 FAIL to PASS flips and 1 regression. Subset 2 (cross-domain: matplotlib + scikit-learn + sphinx) baseline 18/29 = 62.1 percent, treatment 20/29 = 69.0 percent, delta +6.9 pts with 2 flips and zero regressions. Combined paired result across 49 instances: 33/49 to 38/49, delta +10.2 pts.

• Cross-domain transfer isolated cleanly — the Subset 2 treatment arm loaded ONLY the 4 Subset 1 constraints (django and sympy directives), holding out the 11 Subset 2 constraints to test whether learning from one repo family generalizes to a different one. Two cross-domain flips with plausible mechanistic explanations grounded in the loaded constraints. Sphinx-9461 is the strongest case: a sympy classmethod constraint transferred to a sphinx classmethod-wrapper unwrapping bug.

• Honest caveats embedded in RESULTS.md — seven explicit limitations including single-trial design, constraint-failure overlap on Subset 1, the small cross-domain transfer rate, one dropped instance due to an upstream SWE-bench pip flag issue, and judge-model self-reference risk. Stated verbatim rather than hidden in an appendix.

• Full reproducibility artifacts — every progress JSONL, predictions JSON, results JSONL, classification JSONL, constraints JSON, and harness report JSON committed in benchmarks/repeat-mistake/. Locked judge prompts in failure_classifier.py and learning_hook.py. Total agent cost across both arms was approximately 90 USD on a Claude Code subscription.

What's new in v0.8.1

• Contradiction-resolution benchmark expansion -- the v0.7.4 24-pair benchmark grew to 105 hand-curated pairs across 19 categories. Six new categories exercise the v0.8.0 schema specifically: source_tool_corroboration, confirmer_overrides_pending, decay_advantage_session_vs_source, decay_advantage_stale_session, evidence_type_user_correction, settled_beats_higher_confidence. Deterministic runner at benchmarks/contradictions-200/run.py; full per-strategy + per-category breakdown at benchmarks/contradictions-200/RESULTS.md.

• Honest framing on the numbers: the new dataset is harder than v0.7.4's 24-pair set because the new categories deliberately test schema awareness (confirmer, evidence_type, decay) rather than raw confidence ranking. Headline numbers: keep_most_sources 99.0%, keep_higher_confidence 81.0%, auto 77.1%, keep_higher_confidence_decayed 90.5% (on the 21 pairs where evidence_type is present), overall 78.2% across all strategies. The original 24-pair v0.7.4 93.5% number is preserved unchanged at benchmarks/contradictions/ and is not invalidated; it tested a different (smaller, easier) corpus.

• The wedge benchmark is v0.9: "does the learning loop measurably reduce repeated coding-agent mistakes on a public task corpus?" The contradiction-resolution work in this release is internal schema-correctness validation. The empirical artifact that maps to the published essay framing — the learning loop is the durable layer — lands in v0.9 with a SWE-bench-style repeat-mistake benchmark.

What's new in v0.8.0

• Domain-aware confidence decay -- new world_model_server/decay.py module with exponential half-life decay per evidence_type. Half-lives: source_code 365d, test 180d, session 14d, user_correction 730d, bug_fix 365d. Decay applies on read (no background task), so the next query_fact call returns the time-corrected confidence. Settled facts (canonical status, or any fact with confirmer != NULL) never auto-transition. Synthesized facts that decay below 0.2 confidence and corroborated facts that decay below 0.1 confidence auto-supersede on read, surfacing rot to the next compaction injection.

• Per-item provenance fields on facts -- three additive columns (source_tool TEXT, confirmer TEXT, last_decay_at TIMESTAMP), all NULL-defaulted, no backfill. source_tool records which tool wrote the fact (e.g. claude_code, codex, cursor, pi, user). confirmer records who confirmed it, distinct from the asserter; NULL means pending, non-NULL means settled. Both are exposed on the Fact model and propagated through create_fact. Honors the public commitment to Patdolitse (anthropics/claude-code#47023) and ferhimedamine (openai/codex#19195).

• Slash command write operations -- two new subcommands. /world-model resolve <id> marks a contradiction as resolved (manual; for confidence-weighted picking use the resolve_contradiction MCP tool). /world-model forget <id> sets invalid_at on a fact (preserved in the audit log; current-only reads skip it from then on). Both are idempotent and report cleanly on unknown ids. Help text now lists both alongside the read-only subcommands shipped in v0.7.6.

• resolve_contradiction accepts confirmer -- when a confirmer argument is provided to the MCP tool or its underlying resolve function, the winning fact gets its confirmer column stamped with that value. This is the spec primitive that distinguishes "the asserter says X" from "X is confirmed by Y" per the working group sketch.

• Antigravity adapter held for the third consecutive release. The 2026-06-13 re-verification found OnCompactionHook declared as InspectHook in the SDK with no TransformCompactionHook and no additional_context return field. The load-bearing memory-injection contract still does not exist in the SDK.

What's new in v0.7.6

• In-agent /world-model slash command -- typed by the user inside the agent harness, surfaces the world model state without leaving the chat. Read-only in v0.7.6 (status, contradictions, recent, help); write operations (resolve, forget) land in v0.8. Works across Claude Code, Cursor, Codex, and pi by intercepting UserPromptSubmit in the existing inject_helper. Returns additionalContext in the strict camelCase shape Codex enforces (deny_unknown_fields), so the same wire-up serves all four harnesses without a per-harness branch.
• world-model status-watch TUI widget -- terminal pane that runs alongside the agent and refreshes every 5 seconds. Shows constraints (total, severity=error, severity=warning), unresolved contradictions, facts (canonical / synthesized / superseded), and last compaction time. Built on the rich library already in the dependency tree; falls back to a plain-text one-shot dump when rich is not installed.
• Antigravity CLI adapter intentionally NOT shipped in this release -- the re-verification on 2026-06-13 against google-antigravity/antigravity-sdk-python HEAD surfaced an architectural gap: OnCompactionHook is declared as an InspectHook (read-only, non-blocking) with no additional_context return field and no TransformCompactionHook subclass. The load-bearing memory-injection contract does not exist in the SDK today. v0.7.6 ships without Antigravity rather than against a contract that cannot do the work.

What's new in v0.7.5

• Codex CLI adapter -- new install-codex CLI subcommand appends a [mcp_servers.world_model] block plus PreToolUse, PostToolUse, PostCompact, and SessionStart hooks to ~/.codex/config.toml. The bundled snippet was verified against openai/codex@main at v0.138.0-alpha (server name uses underscore to dodge the tool-name hyphen-strip in codex-rs/codex-mcp/src/mcp/mod.rs; hook output sticks to camelCase with deny_unknown_fields compliance). Schema regression tests in tests/test_v075_features.py lock the contract down. See adapters/codex/README.md.
• Dual-shape payload normalization in hook_helper and inject_helper -- both helpers now accept either Claude Code's payload shape (event, project_dir) or Codex's (hook_event_name, cwd), so the same Python code drives all four adapters (Claude Code, Cursor, pi, Codex).
• Antigravity CLI adapter intentionally NOT shipped this release -- the Antigravity API surface is still settling (six 1.0.x releases in three weeks, the url field for HTTP MCP servers landed June 3, hook JSON event-name casing remains undocumented). Targeting June 25 for that adapter after the API stabilizes. Detailed reasoning in the v0.7.5 RELEASE_NOTES entry.

What's new in v0.7.4

• AGENTS.md / .agents/skills/ constraint reader -- world-model-mcp now reads declarative project conventions from AGENTS.md, CLAUDE.md, GEMINI.md, and .agents/skills/*.md files and mixes them into PreToolUse enforcement alongside the SQLite-backed constraints. Supports structured fence blocks (```constraint and YAML frontmatter) and heuristic imperative-sentence extraction for prose-style AGENTS.md files. New MCP tool: get_agents_md_constraints. (anthropics/claude-code#6235 has 4,000+ thumbs-up for AGENTS.md as the cross-agent format.)
• Self-hosted Claude Managed Agents deployment guide -- Anthropic's official position: "Memory is not yet supported in self-hosted sessions." world-model-mcp fills that gap. New guide at docs/deployment/managed-agents-self-hosted.md, with a Modal quickstart you can deploy in under five minutes.
• Reproducible contradiction-resolution benchmark -- 24-pair dataset at benchmarks/contradictions/dataset.jsonl, runner at benchmarks/contradictions/run.py, results at benchmarks/contradictions/RESULTS.md. Headline: 93.5% overall accuracy, 100% on keep_higher_confidence and keep_most_sources, with documented honest weaknesses on tie-handling and small confidence gaps. Re-run with python benchmarks/contradictions/run.py. CI workflow guards regressions.

What's new in v0.7.3

• world-model demo -- one command to see every primitive working. Initializes the knowledge graph, seeds reproducible demo data via scripts/demo_seed.py, then exercises each primitive (PreToolUse enforcement, contradiction detection, PostCompact injection, audit log) with real outputs. New users can see the value without writing any code.
• Opt-in telemetry -- off by default, prompted once during world-model setup, inspectable with world-model telemetry --status, disabled with world-model telemetry --disable. No file paths, no code, no identifiers tied to a person. See Privacy and Security for the exact payload.
• pi adapter -- new adapters/pi/ package. world-model-mcp now plugs into earendil-works/pi via pi's extension API (tool_call -> PreToolUse, context -> auto-injection, session_compact -> audit log). Install with world-model install-pi.

What v0.7.0 introduced (still active)

• PostCompact / UserPromptSubmit auto-injection -- when the agent's context is compacted, the hook automatically splices the top constraints and recent canonical facts back into the next turn. Configurable, fails open.
• defer enforcement tier -- PreToolUse now classifies recurring warning-level violations as defer, which pauses headless agents (with graceful fallback to ask on older clients) instead of either hard-denying or silently passing through.
• Confidence-weighted contradiction resolution -- the new resolve_contradiction tool picks a winner using keep_higher_confidence, keep_most_recent, keep_most_sources, or auto. The loser is marked superseded.
• Compaction audit log -- every PostCompact event writes a row with pre/post token counts and what was re-injected. Query with the audit-compactions CLI or export to JSONL.
• Cursor adapter -- harness-neutral hooks under adapters/cursor/. Same Python helpers, different manifest format.
• Streamable HTTP transport (v0.7.2) -- WORLD_MODEL_TRANSPORT=http so the same 25 MCP tools work behind an MCP tunnel for Claude Managed Agents with self-hosted sandboxes. See docs/deployment/mcp-tunnel.md.

Quick Start

Option 1: Desktop Extension (one-click for Claude Desktop)

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

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

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

# 2. Setup 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

You can also re-seed or seed manually at any time:

# Seed from existing codebase
world-model seed

# Re-seed with force (re-processes already seeded files)
world-model seed --force

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

For Claude Managed Agents with self-hosted sandboxes, or any deployment where the MCP server lives behind a firewall and the agent reaches it from Anthropic-side infrastructure, run world-model-mcp in HTTP mode.

pip install 'world-model-mcp[http]'

export WORLD_MODEL_TRANSPORT=http
export WORLD_MODEL_HTTP_PORT=8765
python -m world_model_server.server

Or use the bundled image:

docker compose up -d                    # Dockerfile.http + persistent volume
curl http://127.0.0.1:8765/healthz      # {"status":"ok","version":"0.7.2"}

Full walkthrough including Anthropic MCP tunnels setup: docs/deployment/mcp-tunnel.md.

Stdio remains the default transport for Claude Code, Cursor, and .mcpb installs. Nothing changes for those flows.

Option 4: Run the guided demo (no Claude Code required)

To see every primitive working with real outputs from a real SQLite database before committing to a full install:

pip install world-model-mcp
cd /tmp/wm-test && mkdir -p wm-test && cd wm-test
world-model demo

The demo initializes a knowledge graph, seeds reproducible data, and exercises PreToolUse enforcement, contradiction detection, the PostCompact injection bundle, and the compaction audit log -- with the actual JSON outputs. Re-runs are idempotent.

Option 5: Run inside pi (experimental)

For users of earendil-works/pi:

pip install world-model-mcp           # the Python helpers
world-model install-pi                # writes adapters/world-model-pi/
pi install local:./adapters/world-model-pi

The pi adapter wires the same hook_helper and inject_helper you'd use from Claude Code into pi's tool_call, context, and session_compact events. See adapters/pi/README.md.

Option 6: Run inside Codex CLI (experimental)

For users of OpenAI's Codex CLI:

pip install world-model-mcp                # the Python helpers
python -m world_model_server.cli install-codex
# (appends [mcp_servers.world_model] + hook blocks to ~/.codex/config.toml)
# Restart codex; verify with: codex mcp list

--dry-run prints what would be appended without writing; --force re-appends even if the adapter marker is already present. The bundled snippet uses world_model (underscore) as the MCP server name to dodge Codex's silent hyphen-strip in its tool-name sanitizer. Hook output is camelCase with deny_unknown_fields compliance against Codex's strict Rust schema; the contract is locked down by tests in tests/test_v075_features.py. See adapters/codex/README.md.

Option 7: Run inside OpenClaw (experimental, v0.10)

For users of OpenClaw, the local-first personal AI assistant that routes across WhatsApp, Telegram, Slack, and Discord:

pip install world-model-mcp
python -m world_model_server.cli setup
python -m world_model_server.cli install-openclaw
# Verify: openclaw mcp probe world-model  (should report 27 tools)

install-openclaw merges an mcp.servers.world-model entry into ~/.openclaw/openclaw.json while preserving all other keys in the config file. It defaults the command field to sys.executable (absolute path to the interpreter running the CLI) — necessary because OpenClaw's process spawn does not inherit shell PATH; a bare python3 fails probe with MCP error -32000: Connection closed. Flags: --force (overwrite existing entry), --dry-run (print without writing), --python <abs-path> (override interpreter), --db-path <path> (override WORLD_MODEL_DB_PATH, default .claude/world-model). Relative --python values are rejected as a hard error.

Pure additive integration — OpenClaw ships no native memory layer, so all 27 world-model tools become available to OpenClaw agent turns without capability overlap. Verified end-to-end against OpenClaw 2026.6.11 (e085fa1) on macOS on 2026-07-01. MCP-registration only in v0.10; a TypeScript plugin bundle for typed lifecycle hooks (before_prompt_build, before_tool_call, before_compaction, session_start, ...) is on the v0.10.x roadmap. See adapters/openclaw/README.md.

Option 8: Run inside Hermes Agent (experimental, v0.10)

For users of NousResearch's Hermes Agent:

pip install "world-model-mcp[hermes]"          # the [hermes] extra pulls ruamel.yaml
python -m world_model_server.cli setup
python -m world_model_server.cli install-hermes
# From inside a Hermes session: /reload-mcp   (loads the new server without restarting)

install-hermes merges an mcp_servers.world-model block into ~/.hermes/config.yaml while preserving all other keys — including every comment and blank line in Hermes' heavily-commented 1327-line reference config, via ruamel.yaml round-trip mode. Defaults the command field to sys.executable (absolute path). Flags: --force, --dry-run, --python <abs-path>, --db-path <path>. Relative --python values are rejected as a hard error.

Hermes ships its own bounded memory system (MEMORY.md + USER.md, character-capped, no auto-decay per Hermes docs). world-model-mcp adds the temporal fact graph with per-fact provenance, per-evidence-type decay, and confidence-weighted contradiction resolution on top — additive, not overlapping. The overlap with the exclusive MemoryProvider plugin slot (currently held by ClawMem for many users) is documented in adapters/hermes/README.md. Verified end-to-end against Hermes v0.17.0 (2026.6.19) on macOS: hermes mcp test world-model reports 27 tools. MCP-registration is the v0.10 track; a native MemoryProvider plugin is on the v0.10+ roadmap and ships only if MCP-route adoption warrants.

Option 9: Run inside Continue (experimental, v0.10)

For users of Continue, the OSS coding-agent extension for VS Code and JetBrains (largest OSS coding-agent extension not tied to a platform vendor — reprioritized after the SpaceX/Cursor acquisition):

pip install world-model-mcp
python -m world_model_server.cli setup
python -m world_model_server.cli install-continue
# Reload the Continue extension. In agent mode, world-model tools appear under the "world-model" server.

install-continue writes a standalone <project>/.continue/mcpServers/world-model.yaml following Continue's per-server-file pattern. No config merge is needed because Continue's own docs use one YAML per MCP server in that directory. Defaults the command field to sys.executable (absolute path); rejects relative --python overrides. Flags: --force, --dry-run, --project-dir <path>, --python <abs-path>, --db-path <path>. Continue watches .continue/mcpServers/ in newer builds, so auto-discovery should pick up the new server; if not, reload the extension. MCP tools are available only in Continue's agent mode. See adapters/continue/README.md.

What Gets Installed

your-project/
├── .mcp.json                    # MCP server configuration
├── .claude/
│   ├── settings.json           # Hook configuration
│   ├── hooks/                  # Compiled TypeScript hooks
│   └── world-model/            # SQLite databases (~155 KB)

Features

1. Hallucination Prevention

Before:

// Claude invents an API that doesn't exist
const user = await User.findByEmail(email); // This method doesn't exist

After:

// Claude checks the world model first
const user = await User.findOne({ email }); // Verified to exist

Goal: Reduce non-existent API references by validating against the knowledge graph

2. Learning from Corrections

Session 1: User corrects Claude

// Claude writes:
console.log('debug info');

// User corrects to:
logger.debug('debug info');

// World model learns: "Use logger.debug() not console.log()"

Session 2: Claude uses the learned pattern

// Claude automatically writes:
logger.debug('debug info'); // No correction needed

Goal: Learned patterns persist across sessions and prevent repeat violations

3. Regression Prevention

// Week 1: Bug fixed (null check added)
if (user && user.email) { ... }

// Week 2: Refactoring
// World model warns: "This line preserves a critical bug fix"
// Claude preserves the null check

// Result: Bug not re-introduced

Goal: Detect potential regressions before code execution

How It Works

Architecture

┌──────────────────────────────────────────────────────────┐
│ Claude Code + Hooks                                      │
│ Captures: file edits, tool calls, user corrections       │
└──────────────────────────────────────────────────────────┘
                         |
                         v
┌──────────────────────────────────────────────────────────┐
│ MCP Server (Python)                                      │
│ - 22 MCP tools for querying/recording/predicting          │
│ - LLM-powered entity extraction (Claude Haiku)           │
│ - External linter integration (ESLint, Pylint, Ruff)     │
└──────────────────────────────────────────────────────────┘
                         |
                         v
┌──────────────────────────────────────────────────────────┐
│ Knowledge Graph (SQLite + FTS5)                          │
│ - entities.db: APIs, functions, classes                  │
│ - facts.db: Temporal assertions with evidence            │
│ - relationships.db: Entity dependency graph              │
│ - constraints.db: Learned rules from corrections         │
│ - sessions.db: Session history and outcomes              │
│ - events.db: Activity log with reasoning chains          │
└──────────────────────────────────────────────────────────┘

Key Concepts

1. Temporal Facts: Every fact has validAt and invalidAt timestamps

   • "Function X existed from 2024-01-15 to 2024-03-20"
   • Query: "What was true on March 1st?"

2. Evidence Chains: Every assertion traces back to source

   • Fact -> Session -> Event -> Source Code Location

3. Constraint Learning: Pattern recognition from user corrections

   • Automatic rule type inference (linting, architecture, testing)
   • Severity detection (error, warning, info)
   • Example generation for future reference

4. Dual Validation: Combines two validation sources

   • World model constraints (learned from user)
   • External linters (ESLint, Pylint, Ruff)

MCP Tools

Twenty-two MCP tools available to Claude Code:

1. query_fact

Check if APIs/functions exist before using them

result = query_fact(
    query="Does User.findByEmail exist?",
    entity_type="function"
)
# Returns: {exists: bool, confidence: float, facts: [...]}

2. record_event

Capture development activity with reasoning chains

record_event(
    event_type="file_edit",
    file_path="src/api/auth.ts",
    reasoning="Added JWT authentication middleware"
)

3. validate_change

Pre-execution validation against constraints and linters

result = validate_change(
    file_path="src/api/auth.ts",
    proposed_content="..."
)
# Returns: {safe: bool, violations: [...], suggestions: [...]}

4. get_constraints

Retrieve project-specific rules for a file

constraints = get_constraints(
    file_path="src/**/*.ts",
    constraint_types=["linting", "architecture"]
)

5. record_correction

Learn from user edits (HIGH PRIORITY)

record_correction(
    claude_action={...},
    user_correction={...},
    reasoning="Use logger.debug instead of console.log"
)

6. get_related_bugs

Regression risk assessment

result = get_related_bugs(
    file_path="src/api/auth.ts",
    change_description="refactoring authentication logic"
)
# Returns: {bugs: [...], risk_score: float, critical_regions: [...]}

7. seed_project

Scan the codebase and populate the knowledge graph with entities and relationships

result = seed_project(
    project_dir=".",
    force=False
)
# Returns: {files_seeded: int, entities_created: int, relationships_created: int}

8. ingest_pr_reviews

Pull GitHub PR review comments and convert team feedback into constraints

result = ingest_pr_reviews(
    repo="owner/repo",  # Auto-detected from git remote if omitted
    count=10
)
# Returns: {prs_scanned: int, constraints_created: int, constraints_updated: int}

Documentation

• QUICKSTART.md - 5-minute setup guide
• CONTRIBUTING.md - Contribution guidelines
• RELEASE_NOTES.md - Version history and features

Testing

# Run tests
pytest

# With coverage
pytest --cov=world_model_server --cov-report=html

186 tests covering knowledge graph CRUD, FTS5 search, constraint management, bug tracking, auto-seeding, PR review ingestion, decision traces, outcome linkage, trajectory learning, prediction layer, memory health, contradiction detection, transcript pointers, project identity, and PreToolUse enforcement. See tests/ for details.

Configuration

Environment Variables

# Database location (default: ./.claude/world-model/)
export WORLD_MODEL_DB_PATH="/custom/path"

# Anthropic API key (optional - enables LLM extraction)
# IMPORTANT: Never commit this! Use .env file (see .env.example)
export ANTHROPIC_API_KEY="your-api-key-here"

# Model selection
export WORLD_MODEL_EXTRACTION_MODEL="claude-3-haiku-20240307"  # Fast
export WORLD_MODEL_REASONING_MODEL="claude-3-5-sonnet-20241022"  # Accurate

# Debug mode
export WORLD_MODEL_DEBUG=1

Note: Create a .env file in your project root (see .env.example) - it's automatically ignored by git.

Customizing Hooks

Edit .claude/settings.json to customize which tools trigger world model hooks:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write|Bash",
      "hooks": [...]
    }]
  }
}

Language Support

Currently Supported:

• TypeScript / JavaScript
• Python

Coming Soon:

• Go, Rust, Java, C++

Extensible Architecture: Easy to add new language parsers (see CONTRIBUTING.md)

Privacy and Security

• Local-First: All knowledge graph data stays on your machine.
• Optional LLM: Works without API key (uses regex patterns as fallback).
• Encrypted Storage: SQLite databases are local files (encrypt your disk for security).

Telemetry (opt-in, off by default)

v0.7.3 added anonymous usage telemetry. It is:

• Off by default. You have to explicitly opt in.
• Asked once during world-model setup, with a clear y/N prompt.
• Inspectable: world-model telemetry --status shows the exact JSON payload that would be sent.
• Disable any time with world-model telemetry --disable, or globally with WORLD_MODEL_TELEMETRY_DISABLE=1.
• Skipped in non-TTY environments (CI, scripts) so it never blocks an automated setup.

What we send (only if you opt in):

What we never send: file paths, file contents, rule names, hostnames, IP addresses, API keys, decision-trace text, fact text, or anything else that could identify a person or leak business logic. The full payload schema lives in world_model_server/telemetry.py.

Where it goes: opt-in events are posted to a dedicated private GitHub repo (SaravananJaichandar/world-model-telemetry) as plain issues. There is no third-party analytics service, no cookie, no fingerprint. The PAT embedded in the client is scoped to that one repo with Issues: write only.

API Key Usage (only if you provide ANTHROPIC_API_KEY)

• Entity extraction from code changes
• Constraint inference from corrections
• Never sends: Credentials, secrets, PII

Security Best Practices

• Never commit .env files
• Use .env.example as template
• Store API keys in environment variables or .env files only
• The .gitignore automatically excludes sensitive files

Roadmap

v0.2.x

• Auto-seeding: knowledge graph populates from existing codebase on setup
• PR Review Intelligence: ingest GitHub review comments as constraints
• Relationship tracking: import and dependency graph between entities
• Multi-language support: Python, TypeScript/JavaScript, Solidity, Go, Rust
• CLI query command for knowledge graph lookups
• 40 tests, 8 MCP tools

v0.3.0

• Module-level matching: query by module name finds the file and its contents
• Incremental re-seeding: only re-process files changed since last seed
• Fuzzy entity matching: approximate name search for typos and abbreviations
• Query caching: in-memory cache with TTL for repeated lookups
• Java support: complete multi-language coverage
• MCP server pipeline validation on real projects

v0.4.0

• Outcome linkage: test failures linked to code changes with facts
• Trajectory learning: co-edit patterns tracked across sessions
• Decision trace capture: structured log of agent proposals and human corrections
• Cross-project entity search with project registry
• 5 new MCP tools (13 total), 104 tests

v0.5.0

• Regression prediction, "what if" simulation, test failure prediction
• Multi-project knowledge transfer, memory health, fact TTL/decay
• get_context_for_action pre-edit bundle, constraint violation tracking, find_contradictions
• 20 MCP tools, 151 tests

v0.6.0 — Enforcement, Provenance, Identity

• PreToolUse constraint enforcement hook: deny hard violations at the edit boundary
• Indexed transcript pointers: hydrate any fact back to source conversation
• Project identity decoupling: stable UUID across directory renames
• Content-hash deduplication for facts and constraints
• Auto-generate CLAUDE.md from the knowledge graph
• BetaAbstractMemoryTool subclass for Anthropic SDK integration
• Desktop Extension (.mcpb) packaging for Claude Desktop
• 22 MCP tools, 13 CLI subcommands, 186 tests

v0.7.0 — Auto-injection, defer tier, contradiction resolution, harness adapters

• PostCompact and UserPromptSubmit auto-injection: re-emit top constraints and recent facts after context loss
• defer enforcement tier in PreToolUse: pause headless agents on recurring warning-level violations, with graceful fallback to ask
• Confidence-weighted contradiction resolution: pick a winner using confidence, recency, or source count, with an auto strategy
• Compaction audit log: query and export what was remembered across each compaction boundary
• Cursor adapter package
• 25 MCP tools, 14 CLI subcommands, 220 tests

v0.7.2 — Streamable HTTP transport

• HTTP transport mode for remote / MCP-tunnel deployment
• /healthz endpoint, Dockerfile.http, docker-compose.yml
• docs/deployment/mcp-tunnel.md walkthrough for Claude Managed Agents
• 236 tests

v0.7.3 — Onboarding, telemetry, pi adapter

• world-model demo guided tour for first-time users
• Opt-in anonymous telemetry, off by default, inspectable
• pi-package adapter (adapters/pi/, install-pi CLI)
• 17 CLI subcommands, 256 tests

v0.7.4 (Current) — Interop, deployment, benchmark

• AGENTS.md / .agents/skills/ constraint reader (new MCP tool: get_agents_md_constraints)
• Self-hosted Claude Managed Agents deployment guide + Modal quickstart
• Reproducible contradiction-resolution benchmark (24-pair dataset, CI workflow, RESULTS.md)
• 26 MCP tools, 17 CLI subcommands, 283 tests

v0.7.5

• Codex CLI adapter (install-codex, shipped 2026-06-05)

v0.7.6

• In-agent /world-model slash command (read-only: status, contradictions, recent, help)
• world-model status-watch TUI status widget

v0.8.0

• Decay + provenance schema: source_tool, confirmer, last_decay_at columns on facts. Per-evidence-type TTL with domain-aware half-lives (source_code 365d, test 180d, session 14d, user_correction 730d, bug_fix 365d).
• Slash command write operations (/world-model resolve <id>, /world-model forget <id>).
• resolve_contradiction accepts confirmer to stamp the winning fact as settled.

v0.8.1

• Expanded contradiction-resolution benchmark: 24 → 105 pairs across 19 categories, including 6 new categories that test the v0.8.0 schema (decay, provenance, confirmer).
• Honest per-strategy + per-category RESULTS.md with the v0.7.4 number preserved as baseline.

v0.9 (Shipped 2026-06-24) — Repeat-mistake benchmark on SWE-bench Verified

• Pre-registered SWE-bench Verified benchmark. The empirical test of the central wedge: does the learning loop measurably reduce repeated agent mistakes on a public task corpus? Methodology locked in benchmarks/repeat-mistake/DESIGN.md on 2026-06-17, a week before the benchmark ran. Pre-registered hypothesis, interpretation thresholds, judge prompts, and SWE-bench Pro 7-category failure taxonomy. No goalpost-moving.
• Result: +10.2 pts combined paired delta across 49 SWE-bench Verified instances (baseline 33/49 = 67.3% → treatment 38/49 = 77.6%). Within-domain delta +15.0 pts on django + sympy. Cross-domain delta +6.9 pts on matplotlib + scikit-learn + sphinx with zero observed regressions on 18 baseline passes. 6 FAIL-to-PASS flips, 1 regression. Full per-task tables, mechanistic analysis of the cross-domain flips, and seven explicit limitations in benchmarks/repeat-mistake/RESULTS.md.
• Pre-registered paper preprint with DOI: 10.5281/zenodo.20834508. CC-BY 4.0. PDF and markdown source at benchmarks/repeat-mistake/paper.pdf / paper.md.
• Constraint extraction pipeline grounded in the SWE-bench Pro 7-category failure taxonomy (arXiv:2509.16941). Locked classifier and extractor prompts in failure_classifier.py and learning_hook.py.
• All raw artifacts committed (per-task progress, predictions, scores, classifications, constraints, harness reports) so the benchmark is reproducible from a fresh checkout.
• v0.9.1 patch: restored embedded telemetry token after a release-mechanics miss in v0.9.0 (no methodology change; benchmark numbers unchanged).

v0.9.2 (Shipped 2026-06-30) — Multi-seed replication appendix

• Pre-registered 17-instance multi-seed test per benchmarks/repeat-mistake/SEED_PLAN.md (locked 2026-06-25). Outcome: load-bearing replication 0 of 7; mean paired delta across two seeds is +0.24 per instance, bootstrap 95 percent CI [0.00, 0.47]. The v0.9 +10.2 pts headline was substantially attributable to an unlucky baseline draw. Honest update published per the pre-registered acceptance criteria. Appendix in RESULTS.md and paper.md. Zenodo record updated to version 2.

v0.10 (Shipped 2026-07-01) — Three new adapters

• OpenClaw adapter (MCP registration) + install-openclaw CLI. Registers world-model-mcp as an MCP server inside OpenClaw via python -m world_model_server.cli install-openclaw. Pure additive since OpenClaw ships no native memory layer. Verified end-to-end against OpenClaw 2026.6.11 (e085fa1) on macOS on 2026-07-01: openclaw mcp probe world-model reports 27 tools discovered. See adapters/openclaw/.
• Hermes Agent adapter (MCP registration) + install-hermes CLI. Registers world-model-mcp as an external MCP server inside Hermes Agent. Uses ruamel.yaml round-trip mode to preserve every comment and blank line in the 1327-line reference config.yaml. Verified end-to-end against Hermes Agent v0.17.0 (2026.6.19) on macOS on 2026-07-01: hermes mcp test world-model reports 27 tools discovered. See adapters/hermes/.
• Continue adapter (MCP registration) + install-continue CLI. Registers world-model-mcp as an MCP tool source inside Continue (VS Code + JetBrains). CLI-side E2E verified: the exact stdio spawn Continue would perform returns 27 tools via a live tools/list roundtrip. See adapters/continue/.
• v0.10.1: fixed a stale Zenodo DOI reference (concept vs. version DOI) across README badge, roadmap link, paper.md, and paper.pdf. No code changes.

v0.11 (Shipped 2026-07-02) — Depth after breadth

Depth release. v0.10 expanded surface area to seven runtimes; v0.11 solves real problems for the users we now have. Two signals shaped it: Hermes #47349 (2026-07-01) surfaced the write-side routing gap (MCP surfaces tools but the agent still chooses the destination); and the auto strategy on the v0.8.1 contradiction-resolution benchmark still scored 77.1% because it did not fully consume the confirmer + decay-awareness fields shipped in v0.8.0.

• v0.11.0 A: auto strategy rewrite for resolve_contradiction. Folds in confirmer awareness, per-evidence-type decay, distinct-source-tool counting, and tie-detection. Lifts the v0.8.1 contradiction-resolution benchmark's auto score from 77.1% to 100.0% on the same 105-pair × 19-category dataset. Overall benchmark accuracy across four canonical strategies + the decayed strategy rises from 78.2% to 83.7%. See benchmarks/contradictions-200/.
• v0.11.0 B: Hermes native MemoryProvider plugin + install-hermes-provider CLI. Python plugin implementing Hermes' agent/memory_provider.py ABC (initialize, get_tool_schemas, handle_tool_call, get_config_schema, save_config). Intercepts writes at Hermes' routing layer rather than only surfacing tools — the architectural distinction MCP alone cannot close. Priority was bumped from "conditional on MCP adoption" after #47349 demonstrated real user demand for write-side interception. Ships as world_model_server/hermes_memory_provider/ in the wheel; install-hermes-provider copies the plugin into <hermes_home>/plugins/memory/world-model/. See adapters/hermes-memory-provider/.
• v0.11.1: Content-type routing schema field. Nullable content_type on the Fact model and the facts table, distinguishing rule (always-inject), fact (search-on-demand), and procedure (multi-step workflow). Additive-only migration; existing rows keep NULL and continue to work. Enables the v0.11.0 B MemoryProvider (and future providers) to route writes intelligently instead of dumping everything into one store. Sourced from Hermes #47349 architectural framing.
• v0.11.2: Dogfooding case study. Publishes what the fact graph actually captured about the world-model-mcp codebase in .claude/world-model/: 3 learned constraints with real violation counts (including two release-mechanics rules that map directly to the v0.9.1 telemetry-token miss and the v0.10.1 tagging lesson), 1 bug_fix reflection, 608 facts, 600 entities. Honest about what was NOT captured (empty events / decisions / sessions tables). Reproducibility contract: python scripts/dogfooding_snapshot.py regenerates the committed JSON byte-for-byte. See case-studies/v011-dogfooding/.

v0.12+ (Backlog)

Ordered by priority, not by size of the section they cover. The near-term items are cheap, well-motivated, and unblock user-visible value; the long-term items are expensive and only start to matter for a v1.0 push.

Near-term — do first:

• world-model doctor command. Detects the class of silent misconfigurations that produced the zero-capture state on this repo (hook commands failing with MODULE_NOT_FOUND from unquoted $CLAUDE_PROJECT_DIR, MCP tools reachable but not wired to a project, stale queue files, missing DB, etc.). Would have caught the v0.11.0 shell-quoting bug automatically. Sourced directly from the v0.11.2 dogfooding trace — highest priority.
• Continue --global config-merge path. Deferred from v0.10. Merges into ~/.continue/config.yaml's top-level mcpServers array instead of writing a per-project standalone file. Would use ruamel.yaml round-trip mode (same pattern as install-hermes).
• Cline adapter. VS Code extension pattern similar to Continue. Lower urgency after Cline shipped global AGENTS rules in v3.86; still worth the ~1-session cost.
• Windsurf adapter. Codeium's fork with a growing user base.
• content_type consumers. v0.11.1 shipped the schema field; v0.12 puts it to work in query_fact filters and the Hermes MemoryProvider's handle_tool_call routing.

Medium-term — waits for a signal or opportunity:

• OpenClaw TypeScript plugin bundle for typed lifecycle hooks — will ship only if MCP-only adoption of the v0.10 OpenClaw adapter justifies the plugin work.
• Hermes lifecycle hook integration (sync_turn, on_pre_compress, prefetch, on_session_end, on_memory_write). Layers on top of the v0.11.0 B MemoryProvider.
• Antigravity CLI adapter. Blocked pending a TransformCompactionHook in the SDK for the load-bearing memory-injection contract; unblocks whenever the SDK ships it.
• MCP spec readiness for upcoming spec versions (stateless transport, _meta headers, InputRequiredResult).

Long-term — v1.0 territory, expensive:

• Full-corpus multi-seed replication of the SWE-bench Verified benchmark: all 49 paired instances at 3-5 seeds each. The v0.9.2 update covers a 17-instance subset only. Cost is ~60 hours agent time; the honest bounds from v0.9.2 are already published, so the marginal empirical gain is smaller than the operational cost. Save for a v1.0 push.
• Head-to-head benchmarks against other memory layers (mem0, Letta, Zep, piia-engram, ClawMem). Competitive-positioning value only; do it once, and only once the differentiators are stable enough that the head-to-head numbers are worth locking in.
• Explicit failure-mode-similarity scoring to predict when cross-domain transfer will succeed. Research-heavy; needs the multi-seed data as a precondition.
• Larger task counts per repo; broader corpus coverage beyond the 50-task subset.

Contributing

Contributions are welcome. See CONTRIBUTING.md for:

• Development setup
• Coding standards
• Adding language support
• Writing tests
• Submitting PRs

Areas where help is needed:

• Language parsers (Go, Rust, Java, C++)
• Performance optimization
• Documentation improvements
• Real-world testing feedback

Stats

Project Size:

• ~4,800 lines of code
• 13 Python modules
• 3 TypeScript hook implementations

Storage Efficiency:

• Empty database: ~155 KB
• Per entity: ~500 bytes
• Per fact: ~800 bytes

License

MIT License - Free for commercial and personal use

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions