I built a context engine that saves Claude Code 73% of its tokens on large codebases

yazar

  1. The problem

    • LLM coding agents on large repos burn tokens scanning files. Claude Code on an 829-file codebase consumed 45K tokens just finding the right code. By turn 3 of a conversation, context is gone.
    • Token cost compounds. 20 questions in a session at 45K each is 900K tokens — nearly the entire 1M window. The agent degrades before your work is done.

  2. What Mnemosyne does

    • Sits between your codebase and your LLM. Indexes into SQLite, scores every chunk with 6 retrieval signals (BM25, TF-IDF, symbol search, usage frequency, predictive prefetch, optional dense embeddings), compresses with AST awareness, delivers exactly within your token budget.
    • Zero runtime dependencies. pip install mnemosyne-engine. No API keys, no cloud, no Docker. Works offline.
    • Drop-in integration: add 3 lines to your CLAUDE.md or .cursorrules and the agent queries Mnemosyne before reading files.

  3. The benchmarks

    • Include the full benchmark table from the README.
    • Be specific: “Claude Opus 4.6 with 1M context, tested against HCCValidatorAI (829 files, production codebase) and httpx (100 files, open-source).”
    • Include the honest finding: “Baseline produces slightly more detailed answers by reading source directly. The optimal workflow combines both: Mnemosyne finds the files, Claude reads them.”
    • This honesty is critical. The audience will find the benchmark report on GitHub. If the blog overstates, you lose credibility permanently.

  4. Quick start 

   pip install mnemosyne-engine
   cd your-project
   mnemosyne init && mnemosyne ingest
   mnemosyne query "How does auth work?" --budget 8000

  1. How it retrieves

    • Six signals fused via Reciprocal Rank Fusion. Link to ALGORITHMS.md for the deep dive.
    • AST-aware chunking for Python, Go, Rust, C#, Java, Kotlin, JS/TS.

  2. Integration examples

    • Claude Code (CLAUDE.md snippet)
    • Cursor (.cursorrules snippet)
    • Any agent that can shell out

  3. What it does NOT do

    • Not a replacement for reading source files — it is a file finder that saves you from grep-scanning
    • Dense embeddings are optional (requires onnxruntime) — sparse retrieval handles most queries
    • Query latency is sub-500ms cold, sub-200ms warm — not instant
    • Small repos (under ~50 files) see marginal savings; the value scales with codebase size

  4. Conclusion

    • Open source, AGPL-3.0, commercial license available
    • Links: PyPI, GitHub, ALGORITHMS.md
    • “Try it on your codebase and tell me what breaks”