3. Qarinah: Evidence-linked project memory for coding agents Agent memory should return evidence, not just a story

The Qarinah project offers a novel approach to managing memory for coding agents. Rather than replaying every prior message, which can be cumbersome and impractical, Qarinah keeps an authoritative project record locally. Selected items from this record are compiled into a small context pack specifically for the current task.

Key features of Qarinah include:

1. An opt-in, append-only JSONL event chain for permitted project events and decisions, complete with event IDs and content hashes for traceability.

2. Multiple view options for the context pack: rebuildable graph, SQLite, Markdown, and Open Knowledge Format.

3. A bounded retrieval step that ensures evidence coverage or allows the agent to abstain when necessary.

4. Cross-agent handoffs compatible with Codex, Claude Code, Cursor, the CLI, and MCP clients.

Performance benchmarks show the benefits of this approach. Testing with 240 project-history records across six software scenarios yielded a context compression rate of 98.7148%, reducing the estimated input-context tokens from 442,113 to just 5,682 (a 77.81:1 compression ratio). Importantly, every required target was directly covered in the top five results, with no additional model-written summary items.

Qarinah is licensed under Apache-2.0 and is currently at version 0.1.6. The open-source repository, along with a white paper, Zenodo concept record, and detailed benchmark method, are available for those interested in exploring or providing feedback on this innovative memory management technique for coding agents.