Project / Agent & Engineering
Cairn
Retrieves a few experience cards from a local Markdown library.
A local-first, deterministic experience-retrieval layer: injects a few traceable cards from a Markdown library into agent context. Zero dependencies, offline by default.
v0.1.2 Maintenance
Overview Project overview
Cairn is a local-first, deterministic experience-retrieval layer. At prompt time it retrieves a few high-signal experience cards from a local Markdown library and places them into the agent's context; it neither requires the agent to search proactively nor injects whole documents.
Motivation Why it exists
The same lesson tends to be relearned: experience was never written down, or was written down but not retrieved when it mattered. Cairn targets the three failure classes of loss, dormancy, and misuse — the goal is to deliver a few relevant, traceable, applicable, retractable experiences at the right moment, and otherwise stay silent.
Architecture Key architecture
- Chinese text is segmented by 2-gram, English and identifiers by word; BM25 field weights are summary ×3 > name ×2 > body ×1.
- Candidates must pass three routing gates: normalized score, query-term coverage, and margin over the runner-up; each card is injected at most once per session.
- At most three cards are injected, carrying only name, summary, and path; full text requires an explicit cairn show.
- A declared context scope (--scope / CAIRN_SCOPE) drops entries whose scope does not intersect it as out_of_scope; with no declared scope, behavior is unchanged.
- A single-file core cairn.py with zero third-party dependencies; local Markdown storage plus a rebuildable cache; retrieval and hooks are offline and read-only at runtime by default.
Capabilities Capabilities
- Four hook formats — Claude Code, Codex CLI, plain text, and JSON — plus CLI commands recall / show / audit / lint / explain; explain reports why each candidate was injected or refused.
- Every injection carries score, gate decisions, and paths and is auditable; logs contain no raw prompts; audit covers entries, logs, session files, and derived caches.
- Sanitize refuses to write into the source library and does not overwrite existing targets by default, using atomic writes.
- Declared-scope filtering is a hard gate; lint warns on stale verified_at and scope crowding. v0.1.2 records 230 tests: 127 core + 103 research fixtures, and adds candidate-pool regression tests for hook, recall, and explain.
Limitations Known limitations
- Thresholds are hand-tuned; cairn calibrate is not yet implemented; synonyms are not understood.
- The evaluation set has grown to 80 positive + 60 negative queries but remains small; 2-gram segmentation is coarse for very short queries, and there is no capture loop — add remains manual.
- import parses only top-level scalar frontmatter, not nested YAML; Experience Contract v0 is metadata rather than cryptographic proof, scope gates only when the caller declares it, verified_at does not expire automatically, and conflict detection is not implemented.
- The README is bilingual with docs/ still mostly Simplified Chinese; it is not a general memory layer, knowledge-management platform, or agent security boundary.
- Long task prompts can dilute query-term coverage, and the fixed margin threshold is calibrated on a small library; cards are retrieval hints, not full text.
- CI currently covers Linux with Python 3.9 and 3.12; Windows and macOS are untested.
Validation Testing & validation
- v0.1.2 is the latest maintenance patch; the repository records 230 tests (127 core + 103 research fixtures) and a 12-entry example library.
- The patch passes the full scored candidate pool to the admission gate; contract-ineligible and scope-mismatched entries no longer consume the candidate budget. Hook, recall, and explain each have regression coverage.
- The 80 positive / 60 negative evaluation reports Recall@1 / @3 of 93.8% / 100%, Injection@1 / @3 of 72.5% / 72.5%, and a 3.3% false-injection rate (2/60).
- Hook cold-start p95 is 74.2 ms at 12 entries and 98.5 ms at 1,000 synthetic entries (30 runs each, single-machine sample).
- Trust & Applicability Eval v0 has 13 cases, declared-scope gating passes 3/3, and four known gaps remain; contract-admission eval passes 3/3.
- CI runs Linux with Python 3.9 and 3.12; Windows and macOS are untested. All figures are a regression baseline, not a benchmark.