Skip to content

v0.1.0 — First Experimental Stable Baseline

Choose a tag to compare

@github-actions github-actions released this 25 Oct 15:24
· 11 commits to main since this release

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 start quarantined.
  • 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.
  • verified is a self-declared state, not a signature; verified_at does 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。