Repository navigation
v0.1.0 — First Experimental Stable Baseline
v0.1.0 — First Experimental Stable Baseline
English below · 中文摘要见文末(跳转)
Cairn is a local-first, deterministic experience retrieval layer for AI coding agents.
At prompt time it searches a local Markdown library and injects a small number of
experience cards. No network, no third-party dependencies, single-file core.
This is the first frozen baseline: behaviour, admission contract and test set are
fixed so the project can be tried on real work. It is experimental — read the limitations
before relying on it.
Try it in 30 seconds
git clone https://github.com/mokuyoaxis/cairn.git
cd cairn
CAIRN_HOME=./examples python3 cairn.py recall "docker compose config 密钥"
CAIRN_HOME=./examples python3 cairn.py explain "docker compose config 密钥"Requirements: Python 3.9+. Nothing to install. Runtime data is written only to
examples/cache and examples/log (both gitignored).
What you get
- Prompt-time retrieval — BM25 over Chinese 2-grams and English words; field weights
summary ×3 > name ×2 > body ×1. - Experience Contract v0 admission — only
active + verified + source + verified_at
entries may be injected; imported entries startquarantined. - Three independent gates — normalized score, query-term coverage, margin over the runner-up.
- Declared-scope filter —
--scope/CAIRN_SCOPE, never inferred from the prompt. cairn explain— every candidate with score, coverage and refusal reason.- Hook entry —
--format claude|codex|json|text, fail-open: empty input, malformed JSON
or an empty library produce no output and exit 0. - Library operations —
add,show,ls,import,lint,audit,sanitize,
stats,feedback,nudge,prune-links.
Measured baseline (regression numbers, not a benchmark)
| Metric | Value |
|---|---|
| Tests | 224 passing (121 core + 103 research fixtures) |
| Retrieval eval | 80 positive / 60 negative queries, 12-entry seed library |
| Recall@1 / @3 | 93.8% / 100% |
| Injection@1 / @3 | 72.5% / 72.5% |
| False injection | 3.3% (2/60 negatives) |
| Contract admission | 3/3 cases |
| Trust & applicability | 13 cases; declared-scope gating 3/3; 4 reported gaps |
| Core | cairn.py, 1198 lines, zero third-party dependencies |
| CI | Linux, Python 3.9 and 3.12 |
Found ≠ injected: recall@3 100% does not mean a card entered the context. All thresholds are
hand-tuned and the evaluation library is 12 entries, so these numbers say the pipeline is
stable, not that it generalises.
What was studied and rejected
A four-phase study asked whether Cairn should gate injection on diagnostic-style
applicability (symptoms, signs, differential, trusted facts). It is archived as NO-GO
under the current host contract: the host cannot supply trusted project-level facts, and an
incomplete fact-trust layer introduced security regressions in a prototype.
Summary with findings, corrected errors and methodology limits:
docs/research/taxonomy-feasibility-2026.md.
The offline prototypes remain in eval/ for reproducibility and are not part of the runtime.
Known limitations
- Entries are evidence, not authority: a retrieved card can still be wrong for your task.
verifiedis a self-declared state, not a signature;verified_atdoes not expire
automatically; conflicts between entries are not detected.- No synonym handling; 2-gram tokenisation is coarse for very short queries.
- Technical documentation is written in Simplified Chinese.
- Verified on Linux only (CI: Python 3.9 and 3.12). Windows and macOS are untested.
- Cairn is not a prompt-injection defence and does not replace your sandbox.
Full list: CHANGELOG.md.
中文摘要
Cairn 是面向 AI 编码 agent 的本地优先、确定性经验检索层:在 prompt 时从本地 Markdown
库中检索,把少量经验卡片放进上下文。不联网、零第三方依赖、单文件核心。
这是第一个冻结基线:行为、准入契约与测试集固定,可用于真实工作试用;仍是实验性软件。
- 30 秒试用:clone 后直接
CAIRN_HOME=./examples python3 cairn.py recall "...",无需安装; - 要求:Python 3.9+;运行时数据只写入
examples/cache与examples/log(均已 gitignore); - 准入契约 v0:只有
active + verified + source + verified_at的条目可被注入,导入条目默认隔离; - 三道门(分数 / 覆盖率 / 领先幅度)+ 显式声明的 scope 过滤(绝不从 query 推断);
cairn explain给出每条候选的分数、覆盖率与拒绝原因;- Hook 失败开放:空输入、非法 JSON、空库都不输出且返回 0,不会阻断你的 agent。
实测基线(回归数字,非 benchmark):224 项测试通过;80 正例 / 60 负例;
召回@1 93.8% / @3 100%;注入@1、@3 均为 72.5%;误触发 3.3%(2/60)。
「检索到」不等于「已注入」,也不等于「适用于你的当前任务」。
已研究但未采纳:诊断式适用性门控(症状/体征/鉴别/可信事实)四轮研究后归档为 NO-GO——
当前宿主无法提供可信的项目级事实,且不完整的事实信任层会引入安全回归。
详见研究总结;离线原型保留在 eval/,不属于运行时。
已知限制:条目是证据不是权威;verified 是自我声明而非签名;verified_at 不会自动过期;
条目不检测冲突;无同义词;技术文档以中文为主;仅在 Linux 验证。
完整清单见 CHANGELOG.md。