Krusch Context MCP

Local MCP server: five tools to store, retrieve, and retire project decisions. SQLite by default.

📖 Read the Systems Deep Dive: Check out the published architecture essay Beyond Flat Vector RAG: What Makes krusch-context-mcp Special on krusch.dev, or the local companion guide in docs/WHAT_MAKES_IT_SPECIAL.md.

Krusch Context MCP gives AI coding agents (Cursor, Claude Code, Windsurf, Antigravity) persistent working memory across sessions. It captures architectural decisions, invariants, lessons, and bug diagnoses, warns on near-duplicate memories, maintains temporal lineage when facts are superseded or invalidated, and audits diffs against active constraints.

---

🚫 What This Is Not

• Not a codebase AST or Git indexer: Code symbol search, call graphs, and Git DAG traversal belong in krusch-git or your IDE’s native search.
• Not a 61-tool cafeteria: Collapsed to strictly 5 canonical verbs (~350 prompt tokens) for boring reliability.
• Not a cloud SaaS platform: Runs 100% locally on your machine with zero external cloud dependencies.
• Not a monolithic domain suite: Legal compliance (krusch-law), document ingestion (krusch-nexus), and contract graphs (krusch-biz) live in separate companion repositories.

---

⚡ 30-Second Quickstart

Requires Node.js >= 22.0.0. Run once inside your project repository:

npx krusch-context-mcp init

This command will:

1. Validate Node >= 22.0.0 and initialize .agent/context.db via node:sqlite.
2. Clear stale MCP tool schemas from local IDE caches.
3. Create your project .env with sensible defaults.
4. Seed initial project context and run a diagnostic health check.
5. Print copy-paste JSON configurations for Cursor, Claude Code, and Claude Desktop.

---

🛠️ The 5-Verb Agent Loop

Krusch Context MCP exposes strictly 5 canonical verbs designed to fit into standard coding workflows:

---

🤖 Recommended Agent Protocol

Coding agents should interact with memory at specific lifecycle boundaries:

┌─────────────────────────────────────────────────────────────┐
│ 1. SESSION START                                            │
│    Agent calls retrieve(query: '*', include_state: true)    │
│    -> Obtains active invariants, recent decisions, blockers │
└──────────────────────────────┬──────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────┐
│ 2. DURING WORK                                              │
│    Agent calls remember(content: '...', category: '...')    │
│    -> If near-duplicate returned, agent calls revise(...)   │
└──────────────────────────────┬──────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────┐
│ 3. PRE-COMMIT / PRE-EDIT                                    │
│    Agent calls nudge(trigger: 'pre_commit')                 │
│    -> Audits code against active invariants (max 3 findings)│
└─────────────────────────────────────────────────────────────┘

---

🛡️ Safe Memory Writes: Closed Taxonomy & Deduplication

To prevent memory hallucination and database pollution:

1. Closed Taxonomy: Every write must use one of 5 categories:
   • decision: Architectural choices, design directions, trade-offs.
   • invariant: Non-negotiable rules (e.g., “Use node:sqlite, zero native compiles”).
   • bug: Solved defects, regressions, and root-cause analyses.
   • lesson: Tactical insights and framework discoveries.
   • blocker: Active dependencies or external obstacles.
2. Near-Duplicate Detection: If a proposed memory matches an existing active record ($\ge 0.85$ cosine similarity), the memory is saved with a warning proposing revise(action: 'supersede', target_id: ...). This protects contrasting rules (e.g., “Allow CORS” vs “Do not allow CORS”) while flagging twin facts.
3. Compulsory Invalidation Reasons: Calling revise(action: 'invalidate') strictly requires a non-empty reason.
4. Focused Audits: nudge caps findings at 3 with concrete evidence, rejecting every_turn triggers to eliminate auditor nagware.
5. Span-Grounded Provenance & Drift Self-Healing: Passing provenance: { file, locator, quoted_sentence } to remember computes a normalized SHA-256 anchor_hash and line range (start_line..end_line). On subsequent retrieve(include_state: true) calls, the engine verifies the span on disk—automatically healing line numbers when code shifts above it, or flagging [DRIFTED] when the underlying code changes.

---

🧠 Embedding Reality & Offline Mode

• Zero-GPU Default: If neither Ollama nor an API key is present, the engine runs 100% offline using deterministic keyword extraction, recency scoring, and heuristic tag indexing.
• Local Ollama (Optional): Set OLLAMA_URL="http://127.0.0.1:11434" with EMBED_MODEL="snowflake-arctic-embed2" (8,192-token context, 1024 dims, ~664 MB VRAM, asymmetric query: retrieval via /api/embed; also supports qwen3-embedding MRL 1024d, nomic-embed-text, and legacy bge-large).
• Remote Cloud (Optional): Set OPENROUTER_API_KEY="sk-..." with EMBED_MODEL="baai/bge-large-en-v1.5" (or any 1024-dim OpenRouter embedding model) for zero-local-VRAM embeddings.

---

🐘 When Do You Need PostgreSQL?

• Use SQLite (Default): Perfect for single developers, local IDE sessions, and projects with thousands of decisions—featuring compact Float32Array binary vector blobs (4 KB/row) and an external-content Porter-stemmed FTS5 lexical index. Zero Docker, zero setup.
• Use PostgreSQL (STORAGE_MODE=postgres): Required only when scaling to multi-agent swarms across different machines needing centralized persistence and server-side pgvector HNSW indexing.

---

🔄 Migration from v1.6 / v1.7

• Tool Aliases: Legacy tool names (add_memory, search_memory, compile_state, supersede_memory, invalidate_memory, proactive_nudge) are automatically aliased to the 5 verbs with a deprecation notice.
• Database Path: v1.7 used .agent/memory.db. v1.8+ uses .agent/context.db. Run npx krusch-context-mcp init to migrate.
• See docs/MIGRATION.md for the complete mapping table.

---

🧩 Sibling Architecture

┌─────────────────────────────────────────────────────────────┐
│                 AI Coding Agent (Cursor / Claude)           │
└──────────────────────────────┬──────────────────────────────┘
                               │
               ┌───────────────┴───────────────┐
               ▼                               ▼
┌─────────────────────────────┐ ┌─────────────────────────────┐
│  krusch-context-mcp (v2.0)  │ │   krusch-git (External)     │
│   Project Memory & Steering │ │   Codebase RAG & AST Search │
│       (5 Canonical Verbs)   │ │      (7 Specialized Tools)  │
└──────────────┬──────────────┘ └─────────────────────────────┘
               │
               ▼
┌─────────────────────────────┐
│     .agent/context.db       │
│   (node:sqlite, Node ≥22)   │
└─────────────────────────────┘

Other specialized tools (krusch-nexus, krusch-law, krusch-biz) run as independent MCP servers in their own repositories.

---

💻 IDE Configuration

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "krusch-context": {
      "command": "npx",
      "args": ["-y", "krusch-context-mcp"]
    }
  }
}

Claude Code

claude mcp add krusch-context -- npx -y krusch-context-mcp

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "krusch-context": {
      "command": "npx",
      "args": ["-y", "krusch-context-mcp"]
    }
  }
}

---

📚 Documentation & Specifications

• Canonical Tool Reference: Generated directly from live schemas (npm run docs:generate).
• Architecture & Failure Modes: 2-page specification covering schemas, indexes, and v2.0.0 multi-scale retrieval invariants.
• Setup & Operations Guide: Zero-Docker setup and optional configurations.
• Migration Guide: Step-by-step v1.5 → v1.6 → v1.7 → v1.8 → v1.9.0 → v2.0.0 mapping.
• Episodic Memory Guide: Deep dive into the closed taxonomy and lifecycle.
• Changelog: Version release notes.
• Official ICLR 2026 BEAM Empirical Report: Closed-system full-suite evaluation across all 100 conversations (~178.34M tokens) and 2,000/2,000 questions (100K, 500K, 1M, 10M splits) on 96 GB Blackwell G4 (snowflake-arctic-embed2 8K ctx on SQLite: v2.0.0 reaches 92.58% Hybrid 8K at 100K, 42.23% R@10 at 1M, and 55.54% Hybrid 8K [93.00% IE] + 48.18% / 58.71% E2E QA at 10M, beating cloud past.dev on Contradiction Resolution across all 4 splits and on 10M Multi-Session Reasoning across both Referees [29.54% / 38.33% vs. 28.17%]) with 5/5 zero-leakage verification.
• Evaluation Baseline Notes: Preliminary benchmark fixtures and token-budget metrics.

---

🧪 Testing

# Run full unit & contract test suite (100% SQLite, zero Docker)
npm test

# Check storage and memory health
npm run health

---

License

MIT © kruschdev