Less context. More proof.
Local project memory and a context compiler for coding agents.
Website ·
Documentation·
White paper
DOI
LOCAL-FIRST
EVIDENCE-LINKED
GRAPH-AWARE
OKF-PORTABLE
GOVERNANCE-READY
98.71% less estimated context - 77.81:1 context compression.
442,113 → 5,682 estimated input tokens.
98.71% lower input-context cost at the same token rate. Reproduce it yourself.
Less replay. More room for current code, tools, and cited project memory.
Technical paper · Publication PDF · Zenodo record · Architecture · Benchmarks · Security · Launch plan
What if your coding agents could send 98.71% less repeated project context?
442,113 estimated input-context tokens became 5,682 - 98.71% less repeated context and 77.81:1 context compression, with every required target directly covered in the top five.
Nearly 99% less repeated context. Every selected memory points back to its source.
Successfully verified across React editing, database migration, TypeScript refactoring, web research, production debugging, and governed release work. The evaluated tasks sent 436,431 fewer estimated input-context tokens. At a flat $1 per million uncached input tokens, that compared context slice moves from $0.4421 to $0.0057 - 98.71% less input-context cost under the same unit price. The percentage is independent of the chosen flat unit price; the portable token estimate excludes output, tools, caching, and fixed provider charges. See the
[machine-readable result]and[methodology].
npm install --save-dev qarinah
npx qarinah init .
npx qarinah record \
--kind decision \
--title "Keep releases provenance-bound" \
--body "Publish only the reviewed artifact from the reviewed commit."
npx qarinah build
npx qarinah query "release provenance" \
--minimum-coverage direct \
--max-tokens 1500 \
--format markdown
Start with the five-minute guide, then use the CLI reference, JavaScript API reference, MCP guide, task recipes, or troubleshooting guide.
Your project already contains the decisions and evidence behind its changes. Qarinah lets the next agent query that record and receive a bounded, cited pack selected for the current task. The same local memory can support Codex, Claude Code, CLI workflows, and compatible MCP clients instead of locking project context to one editor.
Qarinah is a local memory compiler for coding agents. It turns permitted agent activity, project structure, and explicitly committed decisions into durable project memory for Codex, Claude Code, CLIs, and governed workflows. It preserves evidence in a typed graph and deterministic Markdown and JSON views, then compiles a bounded cited pack selected for the current query instead of making an opaque summary or a full transcript the source of truth.
Agent memory usually fails in one of two ways: the next model receives too much history, or it receives a compressed story with no way to verify the source. Qarinah keeps the source record and the compact context separate.
Evidence-linkedEvery selected item cites its event ID and content hash. Conflicts, supersession, authority, retention, and time remain explicit. | BudgetedCoverage-aware retrieval compiles a bounded pack instead of replaying the complete project history. | RebuildableThe JSONL chain is authoritative. Graph, index, Markdown, project structure, and OKF are deterministic derived views. | Governance-readyExplicit capture policy, fail-closed coverage, read-only diagnostics, and optional Maqam disclosure controls preserve boundaries. |
Metadata-only capture is the default. Content capture requires explicit workspace consent. Hidden reasoning, private transcripts, credentials, and browser session state remain outside the product boundary.
When a host or orchestrator queries Qarinah before constructing a model request, Qarinah compiles the retained project history into a bounded cited pack first. That same pack can be supplied to a small local model, a large-context model, or a high-reasoning Codex or Claude session. The compiler itself does not need an embedding API, a hosted memory service, or a Qarinah API key.
Packs are requested explicitly. Hosts can call the CLI or JavaScript API, while sensitive automated disclosure can be registered through a separately governed Maqam capability. Qarinah's built-in MCP server remains a zero-write diagnostic surface.
Qarinah records every permitted lifecycle event delivered by a supported host adapter and every decision that a user or governed workflow explicitly commits. It does not claim to infer every cognitive decision automatically.
Supported event classes include prompts, tool requests, tool completions, approvals, artifacts, sources, claims, decisions, summaries, compactions, subagents, completed turns, and failed turns. Relations connect sessions, turns, tool calls, sources, approvals, conflicts, supersession, derived evidence, and produced project structure.
The project graph covers directories, files, content hashes, JavaScript and TypeScript module references, Markdown links, exact source spans, additions, changes, renames, and deletions. See the architecture guide or the editable diagram source.
Qarinah is intentionally small, local, and inspectable:
| Layer | Technology |
|---|---|
| Runtime | Modern Node.js ESM on maintained Node 22, 24, and 26 releases |
| Durable memory | Append-only canonical JSONL events, SHA-256 content and chain hashes, machine-local checkpoints, and renewable write locks |
| Project graph | Typed event, evidence, relation, module, Markdown-link, file, rename, change, and deletion edges |
| Retrieval | BM25, character-trigram typo tolerance, one-hop graph evidence, reciprocal-rank fusion, deterministic diversity, time, authority, retention, conflict, and supersession |
| Context compiler | Complete-output character and token budgets, explicit output headroom, evidence-coverage gates, deterministic citations, and reproducible manifests |
| Human-readable views | Rebuildable Markdown, JSON, graph, index, and Google OKF 0.1 Draft exports |
| Agent integration | Codex and Claude Code lifecycle hooks, strict JSON stdin, local CLI, typed JavaScript API, and stdio MCP diagnostics |
| Infrastructure | No vector database, hosted backend, embedding bill, model provider, daemon, analytics endpoint, or Qarinah API key |
Qarinah requires a maintained Node.js 22, 24, or 26 release.
npm install --save-dev qarinah
npx qarinah init .
The package is designed for local use. It does not require a hosted Qarinah account, embedding service, or Qarinah API key.
npx qarinah init .
is a one-time, explicit opt-in for that exact workspace and capture policy. After a reviewed Codex or Claude Code integration is installed and its host is restarted, supported lifecycle hooks can append permitted events whenever the host emits them. Qarinah can then rebuild the deterministic graph and compile a small cited pack on demand, so the next task does not need the whole retained history replayed into its prompt.
Qarinah is project memory, not an always-running agent or application supervisor. It does not keep Codex or Claude running, prevent provider-side context compaction, capture host activity the host does not expose, or automatically disclose context through MCP. When a host compacts its own conversation, Qarinah preserves only the permitted evidence it actually received and makes that evidence available to an explicit query or separately governed disclosure capability.
npx qarinah init .
npx qarinah record \
--kind decision \
--title "Keep releases provenance-bound" \
--body "Publish only the reviewed artifact from the reviewed commit."
npx qarinah scan
npx qarinah build
npx qarinah query "release provenance" \
--minimum-coverage direct \
--format markdown
npx qarinah doctor
For agent callers, use the strict JSON stdin interfaces so untrusted text is never interpolated into a shell command:
printf '%s' '{"query":"release provenance","format":"json","minimumCoverage":"direct","maxChars":8000}' \
| npx qarinah query --stdin-json
.qarinah/
config.json portable workspace identity and requested policy
events/events.jsonl authoritative append-only event chain
graph/graph.json event and project nodes with typed edges
index/index.json disposable deterministic retrieval index
records/CONTEXT.md human-readable current record
records/okf/ reproducible Markdown interoperability bundle
index/event-ids/ checkpoint-authenticated idempotency projection
Delete any derived graph, index, or Markdown view and run qarinah build
to reproduce it from the verified event chain.
Qarinah can export a verified workspace record as a deterministic Google Open Knowledge Format 0.1 Draft bundle:
npx qarinah export okf
The export is reviewable Markdown with a root index, a chronological log, one concept file per event, typed relations, citations, content hashes, and chain hashes. It can be diffed in Git, inspected without Qarinah, or passed to another system that understands OKF Markdown. The append-only JSONL event chain remains authoritative; OKF is a deterministic, replaceable interchange view rather than a second database or retrieval engine. See interoperability.
Qarinah's dependency-free local retriever combines BM25, character-trigram typo tolerance, one-hop graph evidence, reciprocal-rank fusion, deterministic diversity, explicit supersession, conflict visibility, retention, time, and scoped authority.
Context-pack v2 adds evidence coverage:
{
"coverage": {
"method": "query-term-overlap-v1",
"status": "direct",
"queryTermCount": 2,
"bestExactTermCount": 2,
"bestExactTermRatio": 1,
"directCandidateCount": 3
}
}
minimumCoverage: "partial"
rejects no-evidence packs. minimumCoverage: "direct"
accepts only a record containing every normalized query term. Coverage is a deterministic retrieval diagnostic, not a claim that a model answer is correct.
The repository includes generated, dependency-free plugin runtimes for Codex and Claude Code. Both provide:
- allowlisted lifecycle hooks;
- a Qarinah context skill;
- zero-write
context_status
andcontext_doctor
MCP tools with exact workspace selection for hosts that do not expose MCP roots; - explicit CLI querying for user-directed local workflows.
Codex and Claude Code plugin caches are immutable copies. Reinstall the reviewed plugin and start a new task after an upgrade. Claude requires an explicitly selected absolute Node 22, 24, or 26 executable. Codex still inherits the host's reviewed Node PATH
boundary because its current plugin schema does not expose an equivalent file setting. See host integrations.
Automatic MCP context disclosure remains disabled. A context pack must be explicitly requested or disclosed through a separately governed Maqam capability.
The repository also runs npm run mcp:smoke
against the exact bundled Codex and Claude runtimes. The smoke test starts each stdio server from its packaged manifest, exercises Codex without MCP roots using an exact trusted workspace selector, exercises Claude with negotiated roots, lists the two annotated tools, calls both tools against a temporary trusted ledger, and verifies clean shutdown without stderr output.
Install the reviewed v0.1.0
plugin once in each host:
codex plugin marketplace add AjnasNB/qarinah --ref v0.1.0
codex plugin add qarinah@qarinah
claude plugin marketplace add AjnasNB/qarinah@v0.1.0 --scope user
claude plugin install qarinah@qarinah --scope user
Then opt in from the root of each project that should retain context:
npx -y qarinah@latest init . --capture content
npx -y qarinah@latest scan
npx -y qarinah@latest doctor
Use --capture metadata
when event bodies should not be retained. Content mode records only bounded, redacted fields exposed by supported hooks; it does not parse hidden transcripts or reasoning. At the start of a later task, ask the installed Qarinah context skill for direct evidence related to the task, or run a bounded query:
npx -y qarinah@latest query "checkout dialog focus trap" \
--minimum-coverage direct \
--max-tokens 1500 \
--reserve-tokens 200 \
--format markdown
The returned pack selects complete cited records from the verified event chain. It is not a model-written rolling summary. Plugin installation is host-wide; capture permission and retained context remain project-specific. See host integrations for current private-clone testing, Claude project/local scopes, upgrades, and interpreter trust.
Maqam governs which registered reads and writes are allowed.Cockroach Crawler gathers bounded public source records.Qarinah remembers decisions, evidence, provenance, and outcomes.ProductLoop orchestrates workflows across those explicit boundaries.
These are composable packages, not one silently merged runtime. Qarinah also works without the other packages.
- no capture outside an explicitly initialized and machine-trusted workspace;
- revocation state stored outside the repository;
- metadata-only capture by default;
- bounded recursive redaction and strict event, log, context, path, and scan limits;
- renewable append locks, linked-path rejection, hash chaining, rollback checkpoints, and deterministic rebuilds;
- context treated as untrusted data, never executable instructions;
- explicit no-evidence and fail-closed retrieval modes;
- no transcript parsing or hidden chain-of-thought capture;
- no model provider, database, daemon, analytics endpoint, or Qarinah API key required.
Content-mode redaction cannot prove that arbitrary tool output contains no secret. Keep metadata mode unless retained content has already been reviewed. See security, privacy, and threat boundaries.
| Command | Purpose |
|---|---|
qarinah init [path] |
|
| Opt a workspace into metadata or content capture | |
qarinah policy / qarinah trust |
|
| Review and approve the exact machine-local capture policy | |
qarinah record |
|
| Append a validated decision, source, claim, approval, or other event | |
| `qarinah hook codex | claude` |
| Normalize one supported host lifecycle event from stdin | |
qarinah scan |
|
| Record a bounded project structure snapshot | |
qarinah build |
|
| Verify and rebuild graph, index, and Markdown | |
qarinah query |
|
| Compile a coverage-aware, cited, budgeted context pack | |
qarinah export okf |
|
| Build a deterministic Markdown interoperability bundle | |
qarinah doctor / qarinah status |
|
| Verify integrity or inspect current state | |
qarinah untrust |
|
| Revoke local capture permission without deleting project files |
Run:
npm run evaluate:software-tasks
npm run evaluate:long-document
npm run evaluate:context
npm run benchmark
| Software task | Full history + current sources | Qarinah + same sources | Reduction |
|---|---|---|---|
| React accessibility edit | 73,765 estimated tokens | 1,025 estimated tokens | 98.61% |
| Database schema migration | 73,703 | 968 | 98.69% |
| TypeScript codebase refactor | 73,628 | 895 | 98.78% |
| Web research to implementation | 73,693 | 963 | 98.69% |
| Production regression debugging | 73,697 | 954 | 98.71% |
| Governed release preparation | 73,627 | 877 | 98.81% |
| Weighted total | |||
| 442,113 | |||
| 5,682 | |||
| 98.71% |
The software-task evaluator keeps the required current source snippets on both sides and replaces only accumulated-history replay. Its estimates use ceil(characters / 4)
; they are not provider usage receipts. The release also successfully verifies exact retrieval, typo tolerance, graph evidence, conflict visibility, and supersession. See BENCHMARKS.md for the committed sources, machine-readable results, commands, and arithmetic.
The long-document evaluator adds a fixed 600-token ceiling over a deterministic 34,751-estimated-token handbook fixture. All 16 exact and typo-tolerant lookups return the cited answer-bearing section at rank 1, with an average pack of 534 estimated tokens and a worst-case estimated reduction of 98.4%; four unsupported questions fail closed when the caller requires direct evidence coverage. This is a segmented synthetic retrieval fixture - not whole-book summarization, native PDF ingestion, or provider-billed token usage.
Qarinah source code is available under Apache License 2.0. Apache-2.0 permits commercial use, modification, and redistribution under its terms. Copyright, a contributor sign-off policy, product execution, and a distinct brand can preserve project stewardship, but an open-source license cannot prohibit compliant commercialization.
See contributing, governance, third-party notices, brand use, support, and launch gates.