Evidence-linked memory for coding agents: a reproducible alternative to replaying project history

Coding agents often inherit project context in one of two ways:

1. replay a long transcript or project history, which is expensive and noisy; or
2. pass along a short summary, which is compact but difficult to audit.

There is a useful third design: keep an authoritative local record, derive searchable views from it, and compile a small task-specific context pack whose claims point back to exact evidence.

This article explains that pattern through Qarinah, an open-source implementation for software projects. The interesting part is not a particular CLI. It is the separation of authority, retrieval, and model-facing context.

The core idea: memory is a compiler, not a transcript

Treat retained project activity as source material rather than as the prompt itself.

permitted events and decisions
            |
            v
authoritative append-only ledger
            |
            +--> rebuildable SQLite / graph / Markdown views
            |
            v
bounded, task-specific retrieval
            |
            v
cited context pack for the next agent

The ledger answers: What was actually retained, by whom, and in what order?

The projections answer: How can we search and navigate it efficiently?

The context compiler answers: What is the smallest complete evidence set this task should receive?

Keeping those questions separate prevents a convenient index—or an opaque rolling summary—from silently becoming the source of truth.

Five architecture choices that make the pattern auditable

1. Capture is explicit and scoped

Qarinah initializes per workspace. A machine-local permit controls whether allowed metadata or reviewed content may be retained. It does not scrape hidden reasoning or private transcript stores.

That boundary matters: a memory system should not gain authority merely because an agent can call it.

2. One event chain is authoritative

Canonical JSONL events bind identifiers, provenance, confidence, typed relations, the previous hash, a content hash, and a record hash. The chain establishes continuity relative to a verified checkpoint.

It does not magically prove every recorded claim is true. Provenance and truth are different properties, and the data model keeps confidence classes such as claimed, inferred, and verified distinct.

3. Search state is disposable

SQLite FTS5, a graph, lexical indexes, Markdown views, project-structure views, and OKF exports are derived from the ledger. If a projection becomes stale, it can be rebuilt after the authoritative chain verifies.

This is a practical reliability rule: optimize the read path aggressively, but never make the optimization irreplaceable.

4. Retrieval composes relevance with authority

The retrieval path combines lexical ranking, typo tolerance, graph relations, time, freshness, repository identity, conflicts, supersession, diversity, evidence coverage, and complete-output budgets.

Optional semantic rerankers can reorder already admitted evidence, but they cannot introduce authority. This distinction lets teams experiment with retrieval without allowing a model or embedding service to widen the disclosure boundary.

5. The output carries citations and may fail closed

Each selected item records an event ID and hash. Callers can require direct evidence coverage. If the complete cited pack cannot satisfy that requirement within the configured boundary, the query can abstain rather than return a confident-looking partial memory.

For agent workflows, an explicit “insufficient evidence” result is often more useful than an uncited answer that merely sounds continuous.

A minimal local setup

Install Qarinah inside a project and opt in to the hosts and capture mode you want:

npm install --save-dev qarinah
npx qarinah setup . --codex --claude --cursor --capture content --allow-query

The --capture content flag is an explicit choice. Use metadata-only capture when event bodies should not be retained.

Record a reviewed decision, rebuild the derived views, and request a directly cited pack:

npx qarinah record \
  --kind decision \
  --title "Keep releases provenance-bound" \
  --body "Publish only the reviewed artifact."

npx qarinah scan
npx qarinah build
npx qarinah query "release provenance" \
  --minimum-coverage direct \
  --format markdown
npx qarinah doctor

The important behavior is not that a search result exists. It is that the result fits a declared budget, exposes its evidence identities, and can be regenerated from the verified local record.

Measuring context reduction without overstating it

“Uses fewer tokens” is easy to claim and surprisingly easy to measure badly. A useful evaluation must say exactly what was replaced and what remained constant.

Qarinah's committed software-task fixture creates 240 retained project-history records and evaluates six reproducible scenarios:

• a React accessibility edit;
• a database schema migration;
• a repository-wide TypeScript refactor;
• web research leading to implementation;
• production regression debugging; and
• governed release preparation.

For every scenario, both paths receive the same current-task source snippets. The baseline additionally receives the complete retained history; the Qarinah path receives the cited pack compiled for that task.

The evaluator uses the portable estimate ceil(characters / 4). It is deterministic, but it is not a provider billing receipt.

Compared context slice	Estimated tokens
Full-history replay across six tasks	442,113
Qarinah packs plus the identical task sources	5,682
Reduction	98.7148%
Compression ratio	77.81:1

Every required target in this fixture had direct evidence coverage in the top five, and the packs contained zero model-written summary records.

Those qualifications belong beside the number. The result measures repeated input-context volume on this fixed fixture. It does not establish universal model quality, latency, provider-native usage, total application cost, or the same reduction on every repository.

You can inspect the benchmark method and limitations, the machine-readable six-task result, and the evaluator in the repository. To reproduce it from source:

git clone https://github.com/AjnasNB/qarinah.git
cd qarinah
npm ci
npm run evaluate:software-tasks

What this design changes in an agent workflow

A cross-agent handoff no longer has to mean “copy the conversation.” The next tool can receive a compact pack containing the relevant decision, implementation outcome, conflict, source identity, and evidence hash.

That has several useful consequences:

• Agent changes are less disruptive. Codex, Claude Code, Cursor, a CLI client, or an MCP client can query the same project-local record through supported integration boundaries.
• Derived memory is reviewable. A human can inspect the Markdown or dashboard view without treating it as a second authority.
• Corrections stay visible. Supersession and contradiction are relations, not destructive edits to history.
• Temporal queries become possible. A query can resolve what was valid at a chosen time rather than flattening every old and new claim together.
• Repository boundaries remain explicit. Cross-repository relationships aid navigation without merging permissions or evidence authority.

This is not a replacement for source code, tests, logs, or the current task's working set. It is a way to avoid repeatedly shipping unrelated retained history alongside those sources.

Design lessons you can reuse without Qarinah

If you are building your own agent-memory layer, four questions expose most architectural problems:

1. What is authoritative? If the vector database disappears, can you reconstruct the memory from a verified record?
2. Who grants capture and disclosure authority? Can agent input widen its own scope?
3. Can every model-facing item name its evidence? A citation should be part of the output contract, not a post-processing decoration.
4. What exactly does the benchmark replace? Keep current-task sources constant, publish the estimator, commit the fixtures, and state what the result does not prove.

A smaller prompt is valuable. A smaller prompt whose contents can be traced, rebuilt, and refused when incomplete is much more useful.

Explore, reproduce, or contribute

• Qarinah website and documentation
• Source code and issues on GitHub
• qarinah on npm
• Published technical paper on Zenodo
• Benchmark methodology
• Contribution guide

Qarinah was created and is maintained by Ajnas N B. Contributions are welcome—especially reproducible fixtures, retrieval edge cases, integration feedback, documentation improvements, and reviews of evidence or privacy boundaries.