Skip to content

Releases

v0.1.2 — Candidate Admission Maintenance

Choose a tag to compare

@github-actions github-actions released this 06 Nov 12:40

v0.1.2 — Candidate Admission Maintenance

Status: released 2026-11-06.

Cairn is a local-first, deterministic experience retrieval layer. v0.1.2 is a
maintenance patch for the v0.1.1 baseline. It fixes one candidate-selection defect
and publishes the sanitized research records that motivated the change.

Try it

python3 cairn.py --version
python3 -m unittest discover -s tests -q

What changed

  • The hook, recall and explain paths now pass the full scored candidate pool to
    the gate. Contract-ineligible and scope-mismatched entries no longer consume the
    candidate budget before eligible entries are considered.
  • Added regression tests for hook, recall and explain, covering unverified peers
    and declared-scope mismatches.
  • Published two sanitized research notes: retrieval boundaries and long-task
    prompt length.

What did not change

  • The Experience Contract, three score gates, declared-scope semantics and hook
    output format are unchanged.
  • No new command, field, dependency, network path or host adapter.
  • The research notes are observations, not roadmap commitments.

Verification

  • Unit tests: 230 passing (127 core + 103 research fixtures).
  • Retrieval eval: 80 positive / 60 negative; recall@1 93.8%, recall@3 100%,
    injection@1/@3 72.5%, false injection 3.3%.
  • Contract admission eval: 3/3.
  • Trust & applicability eval: 13 cases; hard failures 0; four known gaps remain.
  • Hook cold-start p95: 74.2 ms at 12 entries and 98.5 ms at 1,000 synthetic
    entries (30 runs each, single-machine sample).
  • Core: 1,200 lines; zero new dependencies; Python 3.9 AST parse passes.

Known limitations

The v0.1.1 limitations remain unless explicitly fixed here. In particular,
long task prompts can dilute query-term coverage, the fixed margin threshold is
calibrated on a small library, cards are retrieval hints rather than full text,
verified is self-declared, scope gates only when declared, verified_at does not
expire automatically, and conflict detection is not implemented.

中文摘要

2026-11-06 已发布。

v0.1.2 是 v0.1.1 的维护补丁,修复候选池在准入前被截断的问题:
hook、recall、explain 现在把完整评分候选池交给 gate,不合格或 scope 不匹配的
候选不会挤掉合格目标。新增 hook/recall/explain 的候选池回归测试,
并发布两篇去敏后的研究记录(检索边界、长任务 Prompt 长度)。

验证结果:230 项测试通过(127 核心 + 103 研究夹具);80/60 评测指标保持
93.8% / 100% / 72.5% / 3.3%;12 条库 p95 74.2ms,1,000 条合成库 p95 98.5ms。
未改变 Experience Contract、三道门和 scope 语义。

v0.1.1 — Index Revocation Maintenance

Choose a tag to compare

@github-actions github-actions released this 04 Nov 06:05

v0.1.1 — Index Revocation Maintenance

Status: released 2026-11-04.

Cairn is a local-first, deterministic experience retrieval layer. v0.1.1 is a
maintenance patch for the v0.1.0 baseline. It fixes one cache-invalidation defect
and adds regression coverage; it does not add a feature or change the product boundary.

Try it

python3 cairn.py --version
python3 -m unittest discover -s tests -q

What changed

  • The index cache signature now includes each entry's content SHA-256 in addition
    to its name, mtime, size and ctime. An entry changed from active to archived is
    rebuilt even when the file keeps the same size and mtime.
  • get_index() revalidates the current signature before reusing an in-memory index.
  • The disk cache is rejected and rebuilt when the signature no longer matches.
  • Two regression tests cover the warm-index and cold-cache paths.

What did not change

  • The Experience Contract, gates, scope semantics and hook output are unchanged.
  • No new command, field, dependency, network path or host adapter.
  • Candidate-pool starvation, card truncation, context redelivery, conflict
    adjudication, evidence lineage, fact binding, timeout semantics and phase
    triggers remain out of scope for this patch.

Verification

  • Unit tests: 226 passing (123 core + 103 research fixtures), no expected failures.
  • Retrieval eval: 80 positive / 60 negative; recall@1 93.8%, recall@3 100%,
    injection@1/@3 72.5%, false injection 3.3%.
  • Contract admission eval: 3/3.
  • Trust & applicability eval: 13 cases; hard failures 0; four known gaps remain.
  • Hook cold-start p95: 77.0 ms at 12 entries and 106.0 ms at 1,000 synthetic entries
    (30 runs each, single-machine sample).
  • Core: 1,200 lines; zero new dependencies; Python 3.9 AST parse passes.

Known limitations

The v0.1.0 limitations remain unless explicitly fixed here. In particular,
verified is a self-declared state, scope gates only when declared, verified_at
does not expire automatically, conflict detection is not implemented, and the
cache signature check still has a TOCTOU window between hashing and use.

中文摘要

2026-11-04 已发布。

v0.1.1 是 v0.1.0 的维护补丁,仅修复索引缓存对 active → archived 撤回的传播:
缓存签名加入条目内容 SHA-256,热索引复用前重新校验,磁盘缓存不匹配时重建。
新增热索引和冷缓存两条回归测试。

验证结果:226 项测试通过(123 核心 + 103 研究夹具);80/60 评测指标保持
93.8% / 100% / 72.5% / 3.3%;12 条库 p95 77.0ms,1,000 条合成库 p95 106.0ms。
候选预算饥饿、卡片截断、上下文重交付、冲突、证据谱系、事实绑定、超时和阶段触发
不在本补丁范围内。

v0.1.0 — First Experimental Stable Baseline

Choose a tag to compare

@github-actions github-actions released this 25 Oct 15:24

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。