crewlore

你的编码 Agent 总是在重新摸索团队已经掌握的经验。 crewlore 会读取 Agent 已生成的会话和仓库的拉取请求，提取决策、流程和注意事项，并将它们写入仓库中的纯文本知识手册。每条记录都会引用其来源中的确切原文，并注明团队是采纳了它，还是尝试后决定不采用。它在你的计算机上运行，使用你自己的模型密钥。

用六十秒了解它的功能和用法：

https://github.com/user-attachments/assets/b16cb272-da48-4756-89ba-1cc626629e0c

在终端中体验同样的功能。 下方的录屏展示了内置演示 uv run python scripts/demo.py --step，无需 API 密钥：它会将几段合成会话整理成一本手册，其中包含一条团队尝试后决定不采用的结论。

pipx install crewlore

你需要： Python 3.10 或更新版本；模型密钥（ANTHROPIC_API_KEY 或 OPENAI_API_KEY）或兼容 OpenAI 接口的本地模型；如果要整理拉取请求，还需要 GitHub CLI（gh auth login）；只有运行下方的免密钥演示时才需要 uv。

快速入门

根据团队知识目前所在的位置，有两种开始方式。

你已经在使用 Claude Code。 将 lore 指向它写入磁盘的会话记录。默认情况下，它只读取此仓库自身的会话记录，不会读取计算机上其他项目的内容。

cd my-repo
export ANTHROPIC_API_KEY=...     # or OPENAI_API_KEY, or a local model in .lore/config.yaml
lore init                        # create .lore/ in your repo
lore watch                       # read this repo's transcripts, scrub secrets, compile, prune — on an interval
lore query "billing webhook"     # ask the knowledge layer anything, anytime

你有仓库，但还没有会话记录。 改为整理仓库的拉取请求讨论串。编码 Agent 会在 PR 描述和评审中写下许多推理过程——它们尝试了什么、失败的原因以及遇到的限制——因此，即使从未在本地运行过 Agent 的仓库，也已经有一层知识可供整理：

cd my-repo
export ANTHROPIC_API_KEY=...
lore init
lore import-prs owner/repo       # closed PRs by default, agent-authored only; uses your gh login, stores no token
lore query "billing webhook"

无论选择哪种方式，都可以提交 .lore/，这样队友下次执行 git pull 时就能获得这本手册。它自带的 .gitignore 会将原始会话记录、原始 PR 导出文件、提取缓存和用量计数排除在 git 之外。

pipx install --python python3.13 crewlore

无需 API 密钥即可体验

git clone https://github.com/srijansk/crewlore.git
cd crewlore && uv run python scripts/demo.py

该演示使用内置的合成会话完整运行整个流程，并输出整理后的手册、针对手册的查询结果以及三项检查。这只是用玩具数据演示其机制，并非基准测试。

让你的助手使用它

lore install                      # the /lore skill, for the assistants found on this machine
lore install --project --always-on   # into this repo, plus a short block in CLAUDE.md / AGENTS.md
lore install --project --hooks       # plus Claude Code hooks: a file's claims as it is read and edited

• 该技能会告诉助手：在包含 .lore/ 的仓库中更改代码前，先运行 lore query；将 not adopted 的声明视为已拒绝的工作；像看待队友的评论一样权衡声明，而不是将其视为指令；并使用 lore feedback 反馈。Claude Code、Cursor 和 Gemini CLI 各自有一个技能目录；Codex 则读取跨框架 Agent Skills 目录（~/.agents/skills/，或者使用 --project 时的仓库内 .agents/skills/）。
• **--always-on**会在助手的指令文件（CLAUDE.md、AGENTS.md、GEMINI.md）中添加一个简短的标记区块，或在 Cursor 的 .cursor/rules/ 中添加一条始终生效的规则。
• **--hooks**会为 Claude Code 添加两个钩子。助手读取或编辑文件时，作用范围涵盖该文件的声明会加入上下文；每个范围在每次对话中只加入一次，已拒绝的工作优先显示，且不会被大小上限过滤，因此在编辑前就能看到。每条提示都会显示与其相关的声明，效果与运行 lore query 相同。读者纠正过的声明会标记为 corrected，并附上备注。如果没有内容需要补充，钩子就不会发出提示；无论发生什么，都会以状态码 0 退出，因此没有安装 crewlore 的队友不会受到阻碍；压缩上下文后，已显示的范围会再次出现。
• **不会覆盖你的任何文件。**每个写入的文件都带有 crewlore 标记：安装时不会替换并非由它写入的技能（--force 可覆盖此限制），而 lore uninstall 只会移除带标记的文件、带标记的区块以及 crewlore 自己的钩子条目。
• 无法运行命令的助手（例如 Claude Desktop）请改用 MCP 服务：运行 lore serve，参见 docs/mcp.md。

**也可以将其安装为 Claude Code 插件。**在 Claude Code 会话中：

/plugin marketplace add srijansk/crewlore
/plugin install crewlore@crewlore

该插件使用相同的 /lore 技能（调用方式为 /crewlore:lore）和相同的三个钩子，这些内容均由安装程序自身的文本生成。因此，插件和 lore install --hooks 是实现相同文件效果的两种方式：请选择其中一种，因为同时使用时，Claude Code 会将每个钩子运行两次。插件不包含 Python；技能和钩子会调用 lore 命令，因此仍需在机器上运行 pipx install crewlore。每次 crewlore 发布新版本时，插件版本也会随之更新；运行 /plugin update crewlore@crewlore 获取更新；重启 Claude Code 或运行 /reload-plugins 即可加载插件。

你将获得什么

输入的是原始、杂乱的会话。输出的是一条主张：团队学到的一项可复用经验，由四个部分组成。

• 类型 — decision、procedure、gotcha 或 style 规则。
• 行动 — 未来的会话应据此采取什么行动。
• 锚点 — 源内容中的逐字引用，以及它所在的位置（对于转录文本，格式为 <session>#event-<n>；如果 PR 审查评论提供了位置，则格式为 path:line）。编译器会逐条检查引用是否与源内容匹配，并丢弃引用不匹配的主张，因此知识库中绝不会出现无法查证的引用。
• 采纳情况 — current；如果团队尝试后决定不采纳，则为 not_adopted。

[gotcha] · services/billing

账单 webhook 处理程序缺少幂等性检查，Stripe 重试 webhook 时会导致重复扣款。

应做 — 处理前，根据 Stripe 幂等键去重。

锚点 ses_1#event-3 — "the handler has no idempotency check, so when Stripe retries a webhook the charge is processed again."

未采纳的工作会记录为未采纳。 如果会话或拉取请求表明某种做法经过尝试后未被采纳，主张会明确说明这一点，并指出应改为怎么做：

[decision · not adopted] · services/billing

曾提议将 Stripe 幂等键存储在 Redis 中，但在评审中被否决，因为检查必须在数据库事务中执行。

改为 — 将此键与扣款记录保存在同一个事务中。

锚点 services/billing/webhook.py:88 — "Don't put the key in Redis. Must be inside the transaction."

这很重要：如果记忆架构只能表达“X”，那么“我们尝试过 X，但决定不采纳”就会变成对 X 的笃定断言——表达流畅、引用无误，却不符合实际情况。有关这一设计背后的衡量依据，请参阅下文的研究。

主张会汇总到 .lore/knowledge/README.md 中的知识手册里，按领域分组，并与你的代码一起提交到代码库：

# Team knowledge (compiled by crewlore)

## services/billing

- **[gotcha]** Billing webhook handler lacks an idempotency check; dedupe on the Stripe key.
  - *Do:* Dedupe on the Stripe idempotency key before processing.
  - _anchor_ `ses_1#event-3`: "the handler has no idempotency check, so when Stripe retries a webhook the charge is processed again."
- **[decision · not adopted]** Storing the idempotency key in Redis was proposed and rejected in review.
  - *Instead:* Keep the key in the same transaction as the charge.
  - _anchor_ `services/billing/webhook.py:88`: "Don't put the key in Redis. Must be inside the transaction."

## deployment

- **[procedure]** Run migrations before deploy to prevent missing columns.
  - *Do:* Run `make migrate` before every deploy.

一个真实示例

docs/examples/pydantic-ai-prs/ 是在一台从未运行过 Agent 的机器上，于 2026-10-09 使用默认模型，针对公开的 pydantic/pydantic-ai 仓库（20k+ ⭐）运行 lore import-prs pydantic/pydantic-ai --limit 100 的结果。在最近关闭的 100 个拉取请求中，有 24 个由编码 Agent 编写：18 个已合并，6 个未合并便关闭。它们汇总为 130 条声明，其中 15 条标记为 未采纳，共带有 173 个锚点。保真度检查未丢弃模型提出的任何内容；独立复核每个锚点与已提交讨论串后，也没有发现无法解析的锚点。示例中包含经过清理的源讨论串，因此每个锚点都可以追溯到它引用的事件。

以下是一条来自已合并拉取请求的声明，其中的替代方案曾在审查期间尝试后被否决：

[decision · not adopted] · pydantic_ai_slim/pydantic_ai/models

统一的提示缓存（ModelSettings.cache / Caching）仍保持为可选项。曾尝试将其设为默认开启（在支持缓存的模型上将 cache 默认设为 True），但未予采纳，因为维护者决定将默认开启缓存推迟到 v3。

应采取的做法 — 不要将 cache 默认设为 True；除非用户设置 cache、使用 Caching() 或设置特定于提供方的缓存选项，否则应保持缓存关闭。仅在 v3 重新考虑默认开启。

anchor pr_pydantic__pydantic-ai__7560#event-65 — “根据维护者的决定，除非设置了 cache（或 Caching 功能）或特定于提供方的缓存选项，否则缓存保持关闭；默认开启需等到 v3。”

该示例未记录任何冲突。只有存在证据时，检测器才会标记意见分歧：例如，一条标记为未采纳的声明与一条当前声明并存，或一条声明禁止某事而另一条声明要求这么做。三条都禁止修改仓库 .github/ 目录的声明彼此一致，因此不会被报告为冲突。由此留下的盲点列在下文的限制部分。

较早的快照 docs/examples/pydantic-ai/ 是 2026 年 5 月使用 crewlore 0.1.0 汇总的三个 Claude Code 会话。其 README 说明了它能展示和不能展示的内容。

工作原理

flowchart LR
    S["coding-agent<br/>sessions"] --> I["ingest + scrub<br/>(one session format,<br/>secrets redacted)"]
    P["agent-authored<br/>pull requests"] --> I
    I --> C["compile<br/>(claims with verbatim<br/>anchors + adoption)"]
    C --> R["<b>.lore/</b> in your repo<br/>(knowledge book + claims,<br/>plaintext, git-versioned)"]
    R --> SV["serve<br/>(files + MCP query)"]
    SV --> N["next agent session<br/>inherits the knowledge"]

    SV -. "usage + feedback" .-> AL["lifecycle<br/>(decay · reinforce · retire)"]
    AL -. "lifecycle update" .-> R

    classDef engine fill:#4a5d9e,stroke:#1a2c4d,color:#fff,stroke-width:2px
    classDef artifact fill:#2d6a4f,stroke:#1b4332,color:#fff,stroke-width:2px
    class C engine
    class R artifact

• 摄取 + 清理。 两种来源会写入同一种会话格式。对话记录： 此仓库的 Claude Code 会话文件。拉取请求： 通过 gh CLI 获取，每个 PR 讨论串作为一个会话，包含描述、提交及其消息、带文件和行号的审查评论、批准或请求更改的结论、CI 结果，以及 PR 是否已合并或关闭。在存储或发送给模型之前，都会根据一组经过筛选的秘密信息模式进行清理（API 密钥、云服务和 GitHub 令牌、Slack 和 Hugging Face 令牌、JWT、连接字符串密码、私钥块、password=… 形式）。模式集合及其局限见 docs/scrub.md。
• 编译。 模型会从每个会话中提取候选声明。随后由确定性阶段完成其余工作：针对来源验证每条锚点引文，并丢弃不匹配的内容；根据找到引文的位置推导每个锚点的位置；按内容去重；记录会话之间的分歧，而不是覆盖内容；并根据支持某条声明的独立会话数量评估其权威性。lore compile 会打印每轮中门控机制丢弃的候选锚点和声明数量；这个数字，而非存储库事后给出的“忠实度”，才能说明模型的表现。
• 提供服务。 .lore/knowledge/ 中的 Markdown 手册、lore query 命令、lore install 安装到编码助手中的 /lore 技能，以及一个可选的 MCP 服务，让任何 Agent 都能在会话开始时获取相关内容。
• 生命周期。 每次检索都会被记录。用户和 Agent 可以将声明标记为有影响力或已被取代（使用 lore feedback 或 lore_feedback MCP 工具）。30 天（可配置）内无人阅读的声明会被归档，反复被取代的声明会被退役，有影响力的声明则会得到强化，使手册保持精简，而不是膨胀成一堆无人阅读的内容。用量按机器跟踪；用量文件保存在本地，因此已提交的手册能保持字节级稳定。错误或过时的声明可以更正（lore feedback <id> --corrected "what is true now"）：说明会写入声明旁边的受版本控制文件（与手册一同提交），并在该声明提供服务时一并显示；该声明仍保留在手册中并标记为 corrected，在检索结果中排在未更正声明之后，就像被拒绝的工作仍会保留，而不是被删除。

智能集中在编译阶段；摄取和提供服务刻意保持精简，因此支持另一种编码 Agent 或另一种来源只需编写一个小型适配器，无需重写。“编译”在这里指可重复执行的“会话到声明”转换：每个会话调用一次模型，并通过确定性验证、去重、冲突记录和评分进行封装。

与其他方案的区别

• 与使用自有存储库的记忆服务相比——它们的知识存储在数据库中，你需要通过 API 访问。crewlore 的知识以纯文本形式存放在你的仓库中：可在拉取请求中审查、用 grep 搜索、通过 git log 审计。
• 与每种编辑器各自的记忆相比——这类记忆绑定于某个人和某种工具。crewlore 的手册是团队产物，新成员执行 git pull 即可获得。
• 与手动编写的 CLAUDE.md 或规则文件相比——这类文件事后编写，几周内就会过时。crewlore 从实际发生的事情中提取信息，以引文作为证据，并退役不再被阅读的内容。
• 与对文档分块进行检索相比——这类检索会返回段落。crewlore 返回带有行动和结论的声明，因此读者可以区分决策与被拒绝的备选方案。（目前的检索使用确定性词语重合度，而非嵌入向量——更简单且无需依赖；语义排序已列入路线图。）

为什么要做这个项目

Agent 会话中发现的知识默认是私有的，也默认会丢失。它只存在于某位开发者的对话记录中，因此下一位工程师——以及此后每次运行的 Agent——都会重新阅读相同的文件、重新踩一遍相同的坑，并重新做出团队早已做过的决定。没有一个供人类和 Agent 共同读取的共享层，因此决策会逐渐偏离，漏洞也会再次出现。

crewlore 将这些知识转化为一等、带版本控制的产物，存放在团队已经信任的地方：Git 仓库。

它是什么： 一个编译器，可将会话和拉取请求转化为去重、感知冲突且保留来源信息的团队知识，再提供给任何 Agent。

它不是什么： 托管服务、向量数据库，也不是面向单个 IDE 的个人记忆层。它没有账号、没有云服务，也没有专有存储——编译后的知识是由你掌控的纯文本。

你的数据由你掌控

• 本地优先。 捕获、编译和服务都在你控制的基础设施上运行。将编译器指向你自己的模型提供商，或通过 provider: local 使用本地兼容 OpenAI 的模型（Ollama、LM Studio、vLLM）——所有内容都不会经过任何由 crewlore 运营的服务，因为根本没有这类服务。
• 默认限定范围。 lore compile 和 lore watch 只读取本仓库自己的 Claude Code 对话记录。读取任何其他目录都需要明确选择（--transcripts DIR 或配置中的 capture.transcripts）。
• 纯文本，存放在你的仓库中。 知识层是 .lore/ 下的人类可读 Markdown 和 JSONL 文件，由 Git 管理版本。git log .lore/ 就是你的审计记录。
• 存储前清除机密信息。 消息内容和工具调用参数会在导入时清除机密信息，早于会话写入和任何模型调用。这是一套高精度模式规则，作用底线而非 DLP 保证（参见 docs/scrub.md）。像审查其他更改一样，在拉取请求中审查 .lore/ 差异。
• 原始捕获内容绝不会进入 Git。 .lore/sessions/、.lore/sources/（原始 PR 导出文件）、提取缓存和用量文件均被 Git 忽略；每次写入存储时都会写入忽略文件，而不仅仅是在运行 lore init 时。
• 无需存储令牌。 拉取请求导入通过你已完成身份验证的 gh CLI 进行；crewlore 不会获取或存储 GitHub 令牌。
• 将他人的文本视为不可信内容。 对话记录和拉取请求讨论会以内容无法伪造的分隔符发送给模型，并附带规则：类似指令的文本是内容，不是命令。这会降低有人植入虚假声明的可能性，但无法彻底排除；因此，从现在起编译的锚点会注明引述文本的作者（对于拉取请求，会注明登录名和作者在仓库中的角色；本地对话记录只能识别发言者是人类还是 Agent），每条新声明也都会显示在 .lore/ 差异中。提供给 Agent 的声明作为证据，而非指令；每条占一行，并会清除终端转义序列和不可见字符。威胁模型见 SECURITY.md。

CLI

Git 钩子

lore hook install 会向仓库的 post-commit、post-merge 和 post-rewrite 钩子中添加一段带标记、可移除的代码；lore hook uninstall 会准确移除它添加的内容，lore hook status 会说明每个钩子是否会运行，以及不会运行的原因。简而言之：

• 提交会立即返回。 编译会在后台运行，并将日志写入 .lore/cache/hook.log；lore hook status 会显示日志的最后一行，因此运行失败时可以看到。
• 密钥来自 Git 客户端的环境。 从程序坞启动的 GUI 客户端可能无法获取 Shell 中导出的变量；此时会记录凭据错误，但不影响提交。已提交的 .lore/config.yaml 会决定这些自动编译的行为，因此应像审查代码一样审查对此文件的更改。
• 同一时间只运行一次编译。 Rebase 完成后才会编译一次；如果编译期间其提交被替换，编译会因“HEAD moved”而停止，下一次提交时会追上最新状态。
• post-merge 渲染可能会使工作树变脏。 请像处理其他更改一样审查并提交渲染后的书籍。要永久移除一条声明，请将其所在行的 status 设为 archived，而不是删除该行，否则下一次编译会从缓存中重新生成它。
• 谨慎修改现有钩子。 代码块会放在 Shell 能执行到的位置；无法解析或运行的钩子不会被修改；将 LORE_SKIP_HOOK 设为任意值即可跳过运行。

有关详细信息（锁与 rebase、安装时如何处理现有钩子、status --probe 的检查内容），请参阅 docs/git-hooks.md。

配置

.lore/config.yaml：

model:
  provider: anthropic          # anthropic | openai | local
  name: claude-sonnet-5-5      # any current Claude model works; nothing but the prompt is sent
  # temperature: 0             # only sent if set; current Claude models reject sampling parameters
  # base_url: http://localhost:11434/v1   # for provider: local — Ollama, LM Studio, vLLM
capture:
  transcripts: auto            # this repo's own Claude Code transcripts, or a directory path
  settle_minutes: 10           # a transcript modified more recently is still being written; wait for it (`--settle` overrides per run)
compile:
  watch_interval_seconds: 300
  max_unused_days: 30          # claims nobody reads for this long are archived

请自行提供密钥（ANTHROPIC_API_KEY / OPENAI_API_KEY）；crewlore 绝不会将密钥发送到任何地方。默认的 Anthropic 提供商开箱即用。若要使用 OpenAI 或本地兼容 OpenAI 的模型，请添加 SDK：pipx inject crewlore openai（或 pip install 'crewlore[openai]'）。使用 provider: local 时，不会有任何数据离开你的设备。密钥被拒绝、模型名称未知或模型拒绝某项参数时，运行会以清晰的错误信息停止，而不会谎称成功编译了内容。

adoption 字段背后的研究

在 adoption 字段出现之前，我使用来自公开 AIDev 语料库、由 Agent 编写的拉取请求，测量编译器在读取团队拒绝的工作时会存储什么：从相同仓库中选取 60 个未合并即关闭的 PR 和 60 个已合并的 PR，并由独立模型根据 PR 的实际结果判断每项声明。

后续核查（studies/palm/LABEL_RECHECK.md）发现，60 个被拒绝的拉取请求中，有 35 个的改动最终还是进入了各自的仓库，其中 28 个全部落地，7 个部分落地；有 20 个在 Agent 的拉取请求关闭时或之后两天内落地，其中 12 个是通过维护者自己的拉取请求完成的。表中的计数涵盖全部 60 个。对于约六个月内未落地改动的 25 个 PR，仍有 19 个将至少一项此类声明写入存储，平均占其声明的 43.0%；若将核查认定为符合代码实际情况的声明视为安全，第一行则变为 33 个（共 60 个），占 26.6%。按每种统计口径计算，表中各项差异的方向和显著性都保持不变，摘要器的表现仍与提取器相当。

改变模式的关键在于：在所有未包含该字段的版本中，从被拒绝 PR 提取的 658 条陈述里，有 0 条在自身文本中提及拒绝情况（计入已合并对照组后，1,060 条中有 0 条）。添加该字段后，来自被拒绝 PR 的 196 项声明中有 77 项明确说明了这一点；模型标记为 not_adopted 的 91 项中，有 77 项如此表述。仅仅告知模型结果还不够；只有在要求模型记录判定，并提供用于保存判定的字段后，它才开始写下拒绝情况。

代码、固定的数据修订版本和复现步骤都位于 studies/palm/。这项研究使用 Gemini 模型，通过兼容 OpenAI 的提供方运行 crewlore 的提取器和保真度检查，并另用一个模型进行一致性评判（κ = 0.92）。本仓库是这项研究的主要记录；一篇简短的说明将以预印本形式发布，届时会在此处添加链接。如果 crewlore 对你的研究有帮助，引用信息见 CITATION.cff。

状态、限制和路线图

说明

Alpha 版。 磁盘格式在 1.0 版之前可能会变更；格式变更会列在 CHANGELOG 中。已在 Python 3.10–3.14 上测试，测试套件不会发起网络调用。

• 目前可用： 从 Claude Code 对话记录和 GitHub 拉取请求讨论串中采集内容、清除机密信息、编译流水线（原文锚点门控、派生锚点位置、采纳字段、冲突记录、权威性评分）、知识手册、lore query 和 lore explain、lore review、/lore 技能和 Claude Code 钩子（lore install）、每次提交后进行编译的 git 钩子（lore hook install）、MCP 服务、反馈和更正，以及未使用声明的衰减。
• 值得了解的限制： 检索依赖词语重合，而非嵌入；唯一的对话记录来源是 Claude Code（Cursor、Codex 和 Copilot 会话通过 PR 路径接入）；不会读取拉取请求之外的提交；没有「批准后再提供」门控，因此请在 PR 中检查 .lore/ 差异；冲突检测器仅会在某条声明被标记为未采纳，或禁止另一条声明所建议的做法时标记分歧，因此两个会话只是选择了不同答案时不会触发标记；用量和衰减按机器统计，不会在团队内共享。
• 计划中： 人工「批准后再提供」门控、适配其他编码 Agent 的对话记录适配器、基于嵌入的检索、无需等待提交即可在会话结束时采集内容，以及团队成员间共享用量信号。

参与贡献

欢迎提交问题、参与讨论和提交 PR。新加入？请从发起一场讨论开始——为其他编码 Agent 添加采集适配器是最有价值的首次贡献，而且刻意设计得很小（Claude Code 和 GitHub PR 适配器是两个完整示例）。请参阅 CONTRIBUTING.md，了解本地设置和开发流程。

许可证

MIT — 请参阅 LICENSE。

crewlore 由 Srijan Saket 编写并维护。官方源代码位于 github.com/srijansk/crewlore：自 0.2.0 版起的每个 PyPI 发行版均通过此仓库的发行工作流发布，并附有注明此仓库的来源证明。