Why standard RAG fails coding agents #
Most people think a bigger window or basic embeddings solve memory. They don't. Embeddings find "similar" text, but similarity isn't the same as authority. A snippet from a deprecated README is "similar" to your current task, but it's functionally a lie. You need to know if a newer decision superseded an old one, and you need a citation to prove it.
Qarinah treats project knowledge as "typed events" (decisions, approvals, tool outcomes) with explicit relations like supersedes or blocks. Instead of dumping the whole history into the prompt, it builds a compact, evidence-linked pack specifically for the task at hand.
Real-world performance #
The math on this is actually wild. In an evaluator covering things like TS refactoring and production debugging, the input context dropped from over 442k tokens to about 5.6k. That's a ~98% reduction in repeated context. While your actual bill won't drop by exactly 98% (thanks to output tokens and caching), it's a massive win for speed and accuracy.
AI workflow: Getting it running #
If you want to stop the token bleed, here is the practical tutorial for setting it up.
- Install and init in your project:
npm install --save-dev qarinah
npx qarinah init . --capture content
npx qarinah scan
npx qarinah doctor
- Record a decision so the agent doesn't ask you for the 50th time:
npx qarinah record --kind decision \
--title "Use additive database migrations" \
--body "Add, backfill, switch, then remove. Never rename a production column in place."
Integrating with your tools #
You can plug this directly into your LLM agent setup. It stays local, so you aren't up your whole repo to some random backend.
For Codex:
codex plugin marketplace add AjnasNB/qarinah --ref v0.1.1
codex plugin add qarinah@qarinah
For Claude Code:
claude plugin marketplace add AjnasNB/[email protected] --scope user
claude plugin install qarinah@qarinah --scope user
This turns your project memory into a structured database rather than a giant, expensive scroll of text. Your wallet (and your agent's sanity) will thank you.
Next PWA Caching: Why I'm skeptical of standard Service Workers →