world-model-mcp 0.1.0

MCP server that builds a world model for codebases to prevent hallucinations, repeated mistakes, and regressions

World Model MCP

An experimental MCP server that builds a "world model" for your codebase -- a temporal knowledge graph that learns from Claude Code sessions to reduce hallucinations, repeated mistakes, and regressions.

Status: Alpha (v0.1.0) -- Core knowledge graph and MCP tools work. Hooks pipeline and learning loop are functional but early-stage. Contributions welcome.

---

🎯 What It Does

World Model MCP creates a temporal knowledge graph of your codebase that learns from every Claude Code 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

Think of it as giving Claude a long-term memory of your project.

---

⚡ Quick Start

Installation (3 commands)

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

# 2. Setup in your project
cd /path/to/your/project
python -m world_model_server.cli setup

# 3. Restart Claude Code
# Done! The world model is now active

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   │
└──────────────────────────────────────────────────────────┘
                         ↓
┌──────────────────────────────────────────────────────────┐
│ MCP Server (Python)                                      │
│ • 6 MCP tools for querying/recording facts              │
│ • LLM-powered entity extraction (Claude Haiku)          │
│ • External linter integration (ESLint, Pylint, Ruff)    │
└──────────────────────────────────────────────────────────┘
                         ↓
┌──────────────────────────────────────────────────────────┐
│ 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

Six 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: [...]}

---

📚 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

Tests cover knowledge graph CRUD operations, FTS5 search, constraint management, and bug tracking. 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",  // Customize trigger patterns
      "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 & Security

• Local-First: All data stays on your machine
• No Telemetry: Zero tracking or external data transmission
• Optional LLM: Works without API key (uses regex patterns as fallback)
• Encrypted Storage: SQLite databases are local files (encrypt your disk for security)

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.0 (Next)

• Enhanced entity resolution with fuzzy matching
• Multi-language support (Go, Rust, Java)
• Performance optimizations (query caching)
• Migration tool for database updates

v0.3.0

• Trajectory learning (co-edit patterns)
• Structural embeddings
• Relationship graph visualization

v0.4.0

• World model simulation ("what if" queries)
• Test failure prediction
• Multi-project knowledge transfer

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for:

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

Areas We Need Help:

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

---

Stats

Project Size:

• ~3,500 lines of code
• 11 Python modules
• 3 TypeScript hook implementations

Storage Efficiency:

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

---

🙏 Acknowledgments

Built on the shoulders of giants:

• Context Graph Theory: Foundation Capital, PlayerZero, Graphlit, Glean
• MCP Protocol: Anthropic's Model Context Protocol
• Claude Code Hooks: Continuous Claude v2 patterns
• Knowledge Graphs: Mem0, Cognee, Graphiti architectures

Special Thanks:

• Anthropic team for Claude Code and MCP
• Foundation Capital for the context graphs vision
• Open source community for testing and feedback

---

📜 License

MIT License - Free for commercial and personal use

---

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

⭐ Star History

If you find this project useful, please give it a star! It helps others discover it.

---

Built with ❤️ for the Claude Code community

Making AI coding assistants smarter, one session at a time.