Managing AI Context with a SQLite Knowledge Store and MCP Tools

A common pain point with AI coding agents: CLAUDE.md files grow to thousands of lines, consuming context budget and causing the AI to ignore half the rules anyway. One developer on r/ClaudeAI built a system to solve this — RunawayContext (MIT-licensed, currently used for construction-management integrations across Vista, Procore, Monday.com, etc.).

Architecture

The core idea: move deep knowledge from a flat markdown file into a SQLite database with full-text search (FTS5) and optional vector search via sqlite-vec. Instead of loading everything every session, only a small per-project brief (~150 lines), a global constitution (~200 lines), and a pointer-only “living memory” (~50 lines) are loaded upfront. The AI queries the database on demand using MCP tools like search_lessons and get_chunk.

Key Implementation Details

• Token math: The equivalent ~280K tokens still exist — they’re just in the database, not loaded into context. The AI pulls what it needs mid-task.
• Hard caps in code: The regenerator refuses to write a brief past its 150-line cap. 15 named architectural rules each have associated CI tests that fail the build if the rule drifts.
• Hybrid retrieval: Vector-only search was worse than hybrid. The system blends FTS5 keyword scores with sqlite-vec vector scores for best results.
• Human-in-the-loop: The AI writes new lessons to a drafts inbox. A human must approve before promotion to the knowledge store, preventing noise.
• Preserved voice: Auto-generated briefs contain a hand-curated block delimited by <!-- PRESERVE_START --> markers. The regenerator keeps that section intact while regenerating everything around it.

Lessons Learned

• Enforce rules in code, not policy — every “be careful not to grow” instruction was violated within months.
• Hybrid FTS5 + vector search beats vector-only retrieval.
• Direct AI writes to knowledge store introduce noise; use a drafts inbox with manual approval.

The system is agent-agnostic and the repo is public for anyone to adapt.