# 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](https://theisegoria.github.io/world-model-mcp/) · [Implementation and verification status](IMPLEMENTATION_STATUS.md) · [API](docs/API.md) · [Client setup](docs/CLIENTS.md) · [Architecture](docs/ARCHITECTURE.md)

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

```sh
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:

```sh
./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](docs/MODEL.md).

## Operations

```sh
./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

```sh
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](IMPLEMENTATION_STATUS.md). 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.