# world-model-mcp

This MCP server keeps project memory in a local knowledge graph and checks constraints at the edit boundary. It suits agents that must retain context across sessions.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 24
- Author: SaravananJaichandar
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/SaravananJaichandar/world-model-mcp
- Updated: 2026-09-15
- HTML: https://affpapa.org/en/nevibecode/mcp/world-model-mcp

## What it does

\`world-model-mcp` gives an agent a local SQLite knowledge graph for the codebase. The agent queries that memory on each turn, so corrections persist across sessions and project constraints can be checked before an edit is applied.

The server runs locally and can maintain a signed audit chain. Closed epochs use hybrid Ed25519 and SLH-DSA-SHA2-128f signatures, while `etch-verify` can validate records offline. The Claude Code setup requires an `ANTHROPIC_API_KEY` and starts the server through `uvx`.

Python 3.11+ is required for the server to run. Choose the SQLite database location before connecting it to a project.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `WORLD_MODEL_DB_PATH`, `ANTHROPIC_API_KEY`, `WORLD_MODEL_EXTRACTION_MODEL`, `WORLD_MODEL_REASONING_MODEL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env WORLD_MODEL_DB_PATH=<WORLD_MODEL_DB_PATH> --env ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> --env WORLD_MODEL_EXTRACTION_MODEL=<WORLD_MODEL_EXTRACTION_MODEL> --env WORLD_MODEL_REASONING_MODEL=<WORLD_MODEL_REASONING_MODEL> --transport stdio world-model-mcp -- uvx world-model-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from world-model-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add world-model-mcp --env WORLD_MODEL_DB_PATH=<WORLD_MODEL_DB_PATH> --env ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> --env WORLD_MODEL_EXTRACTION_MODEL=<WORLD_MODEL_EXTRACTION_MODEL> --env WORLD_MODEL_REASONING_MODEL=<WORLD_MODEL_REASONING_MODEL> -- uvx world-model-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from world-model-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "world-model-mcp": {
            "command": "uvx",
            "args": [
                "world-model-mcp"
            ],
            "env": {
                "WORLD_MODEL_DB_PATH": "<WORLD_MODEL_DB_PATH>",
                "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>",
                "WORLD_MODEL_EXTRACTION_MODEL": "<WORLD_MODEL_EXTRACTION_MODEL>",
                "WORLD_MODEL_REASONING_MODEL": "<WORLD_MODEL_REASONING_MODEL>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from world-model-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "world-model-mcp": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "world-model-mcp"
            ],
            "env": {
                "WORLD_MODEL_DB_PATH": "<WORLD_MODEL_DB_PATH>",
                "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>",
                "WORLD_MODEL_EXTRACTION_MODEL": "<WORLD_MODEL_EXTRACTION_MODEL>",
                "WORLD_MODEL_REASONING_MODEL": "<WORLD_MODEL_REASONING_MODEL>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from world-model-mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e WORLD_MODEL_DB_PATH=<WORLD_MODEL_DB_PATH> -e ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> -e WORLD_MODEL_EXTRACTION_MODEL=<WORLD_MODEL_EXTRACTION_MODEL> -e WORLD_MODEL_REASONING_MODEL=<WORLD_MODEL_REASONING_MODEL> world-model-mcp uvx world-model-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from world-model-mcp <command>

## When to use it
- retain project decisions across agent sessions
- check repository constraints before applying edits
- record agent events in a signed audit chain
- verify audit records offline without an account or network

## Example prompts
- Check the project memory before changing the architecture and follow its saved constraints.
- Store this decision for later sessions and use it when editing the repository.
- Inspect the decision history and report whether any event appears tampered with.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md