World Model MCP

Local, evidence-aware research memory shared across Codex and Claude sessions. Preserve what a source reports, what an assistant infers, the assumptions involved, and the evidence that might change a conclusion.

Accepted means human-reviewed for inclusion, not proven true. An accepted hypothesis remains a hypothesis.

Project page and synthetic demo · Implementation and verification status · API · Client setup · Architecture

Start on Apple Silicon macOS

Requires npm for the initial installation. The setup script installs a pinned, project-local Node.js 24 runtime; it does not replace the system Node installation.

git clone https://github.com/theisegoria/world-model-mcp.git
cd world-model-mcp
./scripts/setup.sh
./bin/world-model-mcp open

The inspector opens an authenticated loopback session. New stores are empty. Assistants write pending proposals through MCP; review and acceptance happen in the inspector. The browser demo on GitHub Pages uses fictional in-memory examples and does not connect to a knowledge store.

Persistent data defaults to ~/Library/Application Support/WorldModelMCP/. Override it with --data /absolute/path or WORLD_MODEL_DATA. Keep the same data path across clients to share knowledge; use separate paths for tests.

What is implemented

• SQLite WAL, explicit transactions, immutable events, versioned accepted records, dependency-aware human review, and optimistic concurrency.

• Entities, atomic claims, sources, located evidence, inferences, questions, typed relationships, pending proposals, and reversible merges.

• Seven MCP tools: recall, inspect, record, revise, trace, changes, and review_queue.

• One daemon with private Unix-socket proxies; clients can disconnect without losing the store or service.

• Deterministic English/Japanese lexical and graph retrieval; optional verified local multilingual embeddings.

• A React inspector for evidence, proposal diffs, review, graph navigation, revision history, imports, exports, backups, and semantic settings.

• Explicit document import, versioned lossless JSON, readable Markdown, consistent SQLite backup, and validated restore.

No automatic conversation ingestion, crawling, PDF/OCR ingestion, hosted AI requirement, telemetry, cloud sync, or truth adjudication. Retrieved source content is untrusted data.

Local semantic search

Ordinary queries never download a model. Inspect the exact sizes first, then explicitly install:

./bin/world-model-mcp model install
./bin/world-model-mcp model install --confirm
./bin/world-model-mcp model status
./bin/world-model-mcp model reindex
./bin/world-model-mcp model disable

The pinned quantized multilingual-e5-small artifacts total 135,392,183 bytes. Download verification uses fixed SHA-256 hashes; inference uses local ONNX on CPU. Mean pooling, L2 normalization, query: / passage: prefixes, and token-bounded source chunks are fixed in the embedding configuration. See model provenance.

Operations

./bin/world-model-mcp start
./bin/world-model-mcp status
./bin/world-model-mcp doctor
./bin/world-model-mcp stop
./bin/world-model-mcp import --file notes.md          # preview
./bin/world-model-mcp import --file notes.md --apply  # pending source proposal
./bin/world-model-mcp export --file knowledge.json
./bin/world-model-mcp export --file knowledge.md --format markdown
./bin/world-model-mcp backup
./bin/world-model-mcp restore --file /absolute/backup.sqlite            # preview
./bin/world-model-mcp restore --file /absolute/backup.sqlite --confirm  # validated replacement

Restore validates the input, creates a consistent pre-restore backup, stops the daemon, obtains exclusive ownership, and validates a temporary restored database before replacing the store. Never manually copy only a live SQLite main file and discard its WAL.

Verification

export PATH="$PWD/.runtime/node_modules/node/bin:$PATH"
npm run typecheck
npm run build
npm test
npm run test:e2e
npm run schemas
npm run benchmark

Browser tests use installed Google Chrome. Tests use isolated synthetic stores. Real-client connectivity, assistant workflow behavior, browser automation, visual inspection, and benchmarks are reported separately in the status document. Optional semantic verification requires an explicit model installation; see the commands there.

Human review and privacy

MCP exposes no approval, administration, SQL, shell, or unrestricted file-reading tools. Client namespace configuration is supplied at launch, not by model tool arguments. Proxies hold only the domain capability; administrative capability and browser credentials are separate.

Human review is a workflow safeguard, not an OS-level security boundary against an agent with unrestricted shell access under the same user account. An accepted source report does not certify that its proposition is true. Similarity and repeated citations do not approve, merge, or assess knowledge.

License

MIT for this application. The optional model and all dependencies retain their own licenses; provenance and model artifact hashes are documented separately.