What Makes krusch-context-mcp Special

💡 1. The Core Failure Mode: Why Toy Vector RAG Fails Coding Agents

In early 2026, as autonomous coding agents transitioned from experimental novelties into daily production drivers, engineers encountered a frustrating, universal bottleneck: Agent Amnesia.

Every time a developer opened a new IDE chat session in Cursor, invoked Claude Code in the CLI, or launched an Antigravity agent, the model started from an epistemological blank slate. The agent would:

1. Burn thousands of tokens re-discovering the same project conventions, asking questions the developer had answered three times the previous day.
2. Forget architectural decisions and previous debugging breakthroughs, frequently re-introducing a race condition, syntax incompatibility, or schema deadlock that had already been diagnosed and fixed.
3. Violate implicit project invariants (e.g., "All database operations must go through parameterized transactions" or "Never write directly to disk without a 2PC staged sandbox") unless the human painstakingly re-pasted those rules into the prompt.

The common industry reaction was to connect an external vector database—Pinecone, Qdrant, Chroma, or naive Milvus wrappers—and dump conversational summaries into a flat collection. But software engineering is not a generic prose QA problem. Toy vector RAG catastrophically fails on real-world codebases for three structural reasons:

krusch-context-mcp was built from the ground up to solve these traps: transforming agent memory from an unconstrained dump of strings into a structured, governed, and temporally anchored lifecycle.

🎯 2. The Tool Overload Tax: Why Exposing 60 Tools Breaks LLMs

The second massive failure mode in modern agent systems is tool overload. When developers construct Model Context Protocol (MCP) servers, the natural instinct is to expose every utility function—dozens of granular inspection, deletion, pagination, search, and debugging endpoints. Earlier versions of our own stack once exposed 13 to 26 tools.

Exposing dozens of tools directly to an LLM induces severe, measurable performance degradation:

• Massive Prompt Overhead: Exposing 40 to 60 tool definitions consumes 3,500 to 4,200 prompt tokens on every single turn. Over a 50-turn debugging session, the developer pays an unnecessary 200,000-token tax simply listing tool JSON schemas.
• Decision Paralysis & Tool Hallucination: When faced with overlapping tools (e.g. get_memory, find_memory, search_memory, query_memory, inspect_memory), models suffer from decision entropy, hallucinating nonexistent parameter names or selecting suboptimal retrieval paths.

In v1.8.0, krusch-context-mcp implemented a radical product correction: The 5-Verb Discipline.

⚡ 3. The 5-Verb Discipline: Radical Ergonomics for Agents

Instead of exposing dozens of ad-hoc tools, krusch-context-mcp compresses the entire episodic memory lifecycle into strictly five canonical verbs:

🏷️ 4. The Closed Write Taxonomy: Governing Memory Quality

Unconstrained text dumps quickly degenerate into garbage. If an agent can write arbitrary notes with arbitrary tags, the database fills with conversational fluff ("User said hello", "I looked at file X").

krusch-context-mcp requires every memory to declare a valid category from a strictly enforced closed taxonomy:

• decision: Architectural commitments, structural patterns, and technology selections ("Standardized on Node 22 built-in node:sqlite over better-sqlite3").
• invariant: Non-negotiable code rules enforced during pre-commit ("All HTTP API error responses must follow RFC 7807 problem details").
• bug: Diagnosed root causes and anti-regression rules ("SQLite WAL checkpoint locks occur when concurrent writers run without serial transactions").
• lesson: Framework discoveries, third-party library quirks, and environment behaviors ("Vite 5 requires ESM output when targeting Node 22 runtime").
• blocker: External dependencies, pending PRs, or blocked operational workflows.

Because every entry is classified, retrieve({ include_state: true }) can construct an instantly legible, organized project briefing at session start:

# 🧠 Compiled Project State: my-project

## 🎯 Decisions & Priorities (3)
- #1: Standardized on Node 22 built-in node:sqlite over better-sqlite3
- #4: Decoupled codebase RAG into krusch-git for AST and symbol graphs

## 🛡️ Project Invariants (2)
- #2: All HTTP API errors must use RFC 7807 problem details envelopes
- #5: Test suite must run standalone via npm test without requiring .env

## 🐛 Known Bugs & Blockers (0)
- Zero active blockers.

⏳ 5. Temporal Lineage & Audited Invalidation

How does a software team handle changing architectural decisions? In naive vector systems, you either overwrite history blindly (destroying context) or let contradictory notes coexist without explanation.

krusch-context-mcp implements First-Class Temporal Lineage:

Mandatory Invalidation Justification

When an engineer or agent retires a rule, revise(action: 'invalidate') strictly rejects empty reasons. The caller must provide a mandatory justification:

// Invalidation requires explicit reason
await krusch_context_revise({
  action: "invalidate",
  target_id: 8,
  reason: "Replaced custom file mutex with SQLite atomic transaction locks in v1.8."
});

When future agents ask why a historical pattern was abandoned, the revocation rationale is permanently recorded in the lineage audit log, preventing teams from endlessly re-litigating old debates.

📦 6. Token-Budgeted State Packing: Deterministic Hydration

Language models have finite context windows. Asking an agent to read a sprawling memory store causes prompt overflow, pushes actual code out of the context window, and inflates API costs.

krusch_context_retrieve accepts a strict limit_tokens budget (default: 4,000 tokens) and performs greedy pack reranking:

1. Compiled Project State: Active invariants (highest priority), recent architectural decisions, open blockers, and core lessons.
2. Ranked Semantic Matches: Hybrid semantic vector similarities and lexical keyword matches.
3. Decay Review Candidates: Flagged memories older than 30 days for proactive human/agent review.

The engine computes exact token boundaries and packs items greedily until the budget is saturated, ensuring that session start context is rich, relevant, and mathematically bounded.

💻 7. Zero-Docker, Zero-Compilation Local First (Node 22 SQLite)

Many developer tools fail before they begin because of installation friction: demanding Docker daemons, complex environment variables, or native C++ node-gyp compilation (e.g. better-sqlite3) that breaks across platforms.

krusch-context-mcp v1.8.0 was rebuilt for Zero-Docker, Zero-Native-Compilation Local First:

• Built-in Node 22 SQLite: Leverages the native node:sqlite module (DatabaseSync) available in modern Node.js. Zero C++ compiler required.
• Repo-Local Persistence: Stores project memory right inside your repository at .agent/context.db. It can be checked into git or kept local.
• 5-Second Instant Setup:

  npx krusch-context-mcp init

  In under 5 seconds, this command initializes .agent/context.db, seeds initial project invariants, installs AGENTS.md, and outputs ready-to-use configurations for Cursor, Claude Code, and Windsurf.
• Graceful Degradation: If local Ollama (bge-large @ 1024-d) is available, it uses vector similarity. If no embedding daemon is running, it gracefully falls back to deterministic lexical matching, tag indexing, and recency scoring without throwing an error.
• Optional Fleet Adapter: For multi-machine homelab fleets and distributed servers, setting STORAGE_MODE=postgres connects seamlessly to a shared PostgreSQL + pgvector cluster with zero code changes.

🌲 8. The Great Decoupling: Why Codebase RAG Became krusch-git

Earlier iterations of our context stack attempted to do everything in a single package: AST code parsing, Git commit DAG traversal, symbol call graphs, external documentation, and decision memory.

In practice, bundling codebase search into an episodic memory server created a severe architectural contradiction. In v1.8.0, Codebase RAG was decoupled into its own authoritative server: krusch-git (v1.2.1).

⚡ 9. Inside krusch-git: Git DAG, AST Symbols & Hybrid RRF

While krusch-context-mcp acts as Tier 1 working memory, krusch-git (v1.2.1) serves as Tier 2 codebase intelligence. Built on pure PostgreSQL 16 + pgvector, it indexes raw Git objects and exposes 7 canonical MCP tools:

Mathematical Exponential Temporal Decay

In fast-moving codebases, recent code commits must be prioritized over legacy branches. krusch-git implements mathematical recency decay directly into its search engine:

Under this mathematical model:

• A blob committed today retains 100% of its semantic score.
• After 30 days of inactivity, relevance score gracefully decays by ~26%.
• After 100 days, relevance score decays by ~63%.

Empirical Retrieval Ablation on Foreign Code (`expressjs/express`)

To ensure objectivity, the hybrid search engine was evaluated against frozen benchmark queries on the third-party repository expressjs/express (206 files, 3,354 symbols):

🛡️ 10. The 3-Tier Coding Agent MCP Ecosystem

By separating concerns cleanly, the modern Krusch dev ecosystem provides agents with an authoritative 3-tier operational standard:

┌─────────────────────────────────────────────────────────────┐
│ 1. SESSION START & INVARIANTS                               │
│    krusch-context-mcp: retrieve, remember, revise, nudge     │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. CODE EXPLORATION & ARCHITECTURE                          │
│    krusch-git: search_symbols, dependency_graph, read_blob   │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. STAGED EXECUTION & VERIFICATION                          │
│    krusch-harness: run, task_status, diff, apply_diff        │
└─────────────────────────────────────────────────────────────┘

🤖 11. Drop-In Agent Protocols (Cursor, Claude Code, Antigravity)

An MCP server is only as valuable as the model's protocol adherence. Both krusch-context-mcp and krusch-git ship with standardized, copy-paste AGENTS.md rules:

🔬 12. Official ICLR 2026 BEAM 100K Closed-System Validation

Self-reported agent memory benchmarks are notorious for subtle leakage: tiny 90-character turn stubs that fit whole conversations into 8K tokens, regex ingestion hints tuned to test queries, handicapped baselines, or frontier cloud models grading their own outputs. To eliminate every one of those failure modes, krusch-context-mcp (v1.8.1) was evaluated across all 400/400 validated probing questions (20 multi-session conversations, ~3.06M corpus tokens) of the official ICLR 2026 Mohammadta/BEAM (100K) benchmark inside a hermetic single-box 96 GB NVIDIA RTX PRO 6000 Blackwell environment.

Every embedding, retrieval call, reader completion, and dual cross-family referee judgment ran strictly over 127.0.0.1:11434 loopback with zero cloud API keys (GEMINI_API_KEY="") and four open-weights models co-located simultaneously in GPU VRAM (90.5 GB / 97.9 GB, 100% GPU): bge-large:latest (embeddings), unmodified gpt-oss:120b (Reader), qwen2.5:32b (32B dense primary Referee), and hermes3:latest (8B Llama-3.1 continuity Referee).

🚀 13. Architectural Horizon & Open-Source Ecosystem

Software engineering is evolving from one-off chat completions into long-running, autonomous engineering loops.

In this new era, developer productivity is not determined simply by foundation model parameter count. It is governed by contextual fidelity and architectural boundaries:

• Giving agents a lean, disciplined 5-verb memory store (krusch-context-mcp) prevents amnesia without prompt bloat.
• Decoupling codebase intelligence into an AST-aware Git DAG index (krusch-git) enables topological refactoring without grep hallucinations.
• Gating disk mutation behind sandboxed PostgreSQL test runs (krusch-harness) guarantees that broken code never touches physical files.

Together, this 3-tier ecosystem demonstrates that with disciplined systems engineering, coding agents can operate with human-grade precision, long-term memory, and architectural safety.