Project / Agent 与工程
Cairn
从本地 Markdown 库检索少量经验卡。
本地优先、确定性的经验检索层：从 Markdown 库检索少量可追溯卡片注入 Agent 上下文，零第三方依赖、默认无网络。
v0.1.2 维护版
Overview 项目概述
Cairn 是本地优先、确定性的经验检索层。在 prompt 时从本地 Markdown 库检索少量高信号经验卡，放入 Agent 上下文；它不要求 Agent 主动搜索，也不注入整篇文档。
Motivation 为什么创建
同一个教训常被重复学习：经验没有被写下来，或写下来却在需要时没有被取回。Cairn 针对丢失、休眠和误用三类失败，目标是在正确时机提供少量相关、可追溯、适用、可撤回的经验，否则保持沉默。
Architecture 关键架构
- 中文按 2-gram、英文与标识符按词切分；BM25 字段权重为 summary ×3 > name ×2 > body ×1。
- 候选必须通过三道路由门：归一化分数、查询词覆盖、与第二候选的 margin；同一卡片每个 session 最多注入一次。
- 最多三张卡片，只给 name、summary、path；全文需显式 cairn show。
- 显式声明 scope（--scope / CAIRN_SCOPE）时，scope 不相交的条目会被标记 out_of_scope 并丢弃；未声明时行为不变。
- 单文件核心 cairn.py，零第三方依赖；本地 Markdown 存储 + 可重建缓存；检索与 hook 默认无网络、运行时只读。
Capabilities 已实现能力
- Claude Code、Codex CLI、纯文本与 JSON 四种 hook 格式；提供 recall / show / audit / lint / explain 等 CLI，explain 报告每个候选被注入或拒绝的原因。
- 每次注入都带分数、门决策与路径，可审计；日志不含原始 prompt；audit 覆盖 entries、日志、session 文件与派生缓存。
- Sanitize 拒绝写入源库、默认不覆盖已有目标，使用原子写入。
- 声明 scope 后按 scope 硬过滤；lint 对过期的 verified_at 与 scope 拥挤给出警告；v0.1.2 记录 230 项测试（127 核心 + 103 研究 fixture），并增加 hook/recall/explain 的候选池回归测试。
Limitations 已知限制
- 阈值手工调整；cairn calibrate 尚未实现；同义词不能被理解。
- 评估集已扩到 80 个正例 + 60 个负例，但仍然很小；2-gram 对极短查询较粗；没有 capture loop，add 仍需手动。
- import 只解析顶层标量 frontmatter，不解析嵌套 YAML；Experience Contract v0 是元数据而非加密证明；scope 仅在调用方显式声明时生效，verified_at 不会自动过期，冲突检测尚未实现。
- README 中英双语，docs/ 仍以简体中文为主；它不是通用记忆层、知识管理平台或 Agent 安全边界。
- 长任务 Prompt 会稀释查询词覆盖率，固定 margin 阈值又是在小库上校准的；卡片是检索提示，不是全文。
- CI 目前只覆盖 Linux 的 Python 3.9 与 3.12；Windows 与 macOS 尚未测试。
Validation 测试与验证
- v0.1.2 是最新维护补丁；仓库记录 230 项测试（127 核心 + 103 研究 fixture）与 12 条示例库。
- 该补丁把完整评分候选池交给准入 gate；不合格或 scope 不匹配的候选不再挤占候选预算。hook、recall 与 explain 均有回归覆盖。
- 80 正例 / 60 负例的评测结果为 Recall@1 / @3 93.8% / 100%、Injection@1 / @3 72.5% / 72.5%、误注入 3.3%（2/60）。
- Hook 冷启动 p95 在 12 条库为 74.2ms，在 1,000 条合成库为 98.5ms（各 30 次，单机样本）。
- Trust & Applicability Eval v0 共 13 例，显式 scope 拦截 3/3，仍有 4 个已知缺口；合约准入评估 3/3。
- CI 覆盖 Linux 的 Python 3.9 与 3.12；Windows 与 macOS 尚未测试。所有数字都是回归基线，不是 benchmark。