DEV Community

lh123aa
lh123aa

Posted on

My Claude Code kept forgetting the same decision, so I gave it a local index (33 MB Go binary, no cloud)

Every Wednesday I settle a design decision. Every Friday, a new session asks me what caching approach this project uses.

I open about six sessions a day, and each one starts with roughly ten minutes of re-briefing. That's thirty hours a month spent teaching my agent things it already did.

What I tried first, and why it failed

Stuffing CLAUDE.md. Works until roughly page eight. After that the instructions start fighting each other and the important constraint gets buried.

Cloud memory services. Great products, wrong shape for me. I work in cross-border trade; contracts, quotes and supplier docs live on my machine and are not going to a third party's vector store.

Pasting context each time. I paste 6,000 characters and the model reliably uses the first 2,000.

The pattern: the problem was never that the model is weak. It's that I never gave it access to my own material.

What I built

Cortex is a single Go binary that indexes local files and exposes itself as an MCP server.

cortex index ~/notes ~/work/docs
cortex start
Enter fullscreen mode Exit fullscreen mode

The second command registers an MCP stdio server in Claude Code / Cursor / Trae, backing up the existing config instead of overwriting it.

Design decisions worth explaining:

  1. Hybrid retrieval, not vector-only. Pure embeddings miss exact model numbers and proper nouns; pure BM25 misses paraphrase. Two recall paths, score normalisation, then fusion, then three layers of dedupe (chunk hash → semantic neighbour → rerank).
  2. SQLite + HNSW, in-process. No vector database to operate, no Docker, no GPU. Default is pure BM25; vectors are opt-in.
  3. Ed25519 offline licensing. The public key is compiled into the binary; the license is verified locally. Nothing phones home, and if I disappear the version on your disk keeps running.

Numbers from my own corpus (not a benchmark)

Metric Value
Binary size 33 MB, no runtime deps
Index 4,821 docs / 61,340 chunks 1.2 s
Single hybrid query 75 ms
Test suites 24/24 passing

Pricing, because someone always asks

The core is Apache-2.0. The free tier is 5,000 documents / 1 GB with no feature gating and no card. Pro is $29 one-time for 500,000 documents / 100 GB plus rerank and auto-index. I deliberately did not build a subscription — charging monthly for a local binary never made sense to me.

The docs page auto-switches between English and Chinese based on region, and the checkout currency follows (USD or CNY).

Repo: https://github.com/lh123aa/cortex
Docs: https://cortex.qataroasis.cc

What I actually want from this post

Not signups. I want the failure cases: where does chunking break on your corpus — monorepos, 200-page PDFs, Chinese notes, notebooks with output cells? I'll tune the splitter and publish the diff in a follow-up.

If you try it, reply with your document count and one place recall missed. That's more useful to me than a star.

Top comments (0)