I kept hitting the same problem in long Codex and Claude Code sessions: the agent was capable, but the project memory was expensive.
A new task would trigger another repository scan. Decisions from older sessions had to be explained again. Tool results were buried in transcripts. A summary was smaller, but I could not always tell which source supported a statement or whether a newer decision had replaced it.
So I built Qarinah, an Apache-2.0 local project-memory compiler for coding agents.
A large context window can hold more text, but it does not answer four important questions:
Replaying the full history preserves information, but it also sends large amounts of irrelevant material. A single generated summary is smaller, but it becomes another authority that can omit or blur evidence. Ordinary embedding retrieval finds similar text, but similarity is not the same as authority, recency, or approval.
Qarinah keeps the source record and the context pack separate.
Permitted decisions, tool outcomes, approvals, project structure, and evidence become typed events. Relations connect records such as supersedes, supports, blocks, and produced-by. Deterministic Markdown and JSON views remain inspectable in the repository. When a task begins, Qarinah retrieves a bounded pack and includes citations back to event IDs, hashes, and sources.
The result is not one giant memory prompt. It is a small evidence-linked pack built for the current task.
| Approach | Useful for | What remains difficult |
|---|---|---|
| Full-history replay | Maximum raw recall | Repeated tokens, noise, stale decisions |
| AGENTS.md or CLAUDE.md | Stable instructions | Tool outcomes and changing decisions |
| Embedding retrieval | Similar passages | Authority, supersession, exact provenance |
| Generated summary | Small handoff | Verifying omissions and source claims |
| Qarinah | Compact project memory | Requires explicit workspace opt-in and capture policy |
Install it inside one project:
npm install --save-dev qarinah
npx qarinah init . --capture content
npx qarinah scan
npx qarinah doctor
Record a decision:
npx qarinah record --kind decision \
--title "Use additive database migrations" \
--body "Add, backfill, switch, then remove. Never rename a production column in place."
Then Codex, Claude Code, a CLI workflow, or an MCP client can request the smallest cited pack relevant to a task. The project owns the files. Qarinah does not require up the repository to a hosted Qarinah backend.
The committed evaluator compared full-history input with bounded Qarinah packs across six software tasks covering React editing, database migration, TypeScript refactoring, web research, production debugging, and governed release work.
The compared input changed from 442,113 estimated input-context tokens to 5,682. That is 98.71% less repeated context, or 77.81:1 compression, while every required target ranked in the top five. The repository includes the inputs, arithmetic, methodology, and machine-readable result.
This is a result for that task set, not a promise that every repository or total provider bill drops by exactly 98.71%. Output tokens, caching, tool calls, and provider pricing are separate.
Qarinah ships installable plugins for both hosts.
Codex:
codex plugin marketplace add AjnasNB/qarinah --ref v0.1.1
codex plugin add qarinah@qarinah
Claude Code:
claude plugin marketplace add AjnasNB/qarinah@v0.1.1 --scope user
claude plugin install qarinah@qarinah --scope user
Both can read the same opted-in local project memory. This does not copy private provider chat history between services. It gives both agents access to the same project-owned evidence.
Qarinah is open source and early. I am looking for real failure cases, especially:
Website: https://qarinah.io/
Source: https://github.com/AjnasNB/qarinah
Technical paper: https://qarinah.io/paper/
If you test it, I would rather receive one reproducible failure than ten generic compliments. That is the fastest way to make the project useful.