crewlore

Your coding agents keep relearning what your team already figured out.

crewlore reads the sessions your agents already produce, and your repo's pull requests, pulls out the decisions, procedures and gotchas, and writes them into a plain-text knowledge book inside your repo. Every entry quotes the exact line it came from, and records whether the team adopted it or tried it and declined. Runs on your machine with your own model key.

Sixty seconds on what it does and how it is used:

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

The same thing in a terminal. The recording below is the bundled demo, uv run python scripts/demo.py --step, which needs no API key: a handful of synthetic sessions compiled into a book, including one claim the team tried and declined.

pipx install crewlore

You need: Python 3.10 or newer; a model key (ANTHROPIC_API_KEY or OPENAI_API_KEY) or a local OpenAI-compatible model; the GitHub CLI (gh auth login) if you want to compile pull requests; uv only for the no-key demo below.

Quickstart

Two ways in, depending on where your team's knowledge currently lives.

You already use Claude Code. Point lore at the transcripts it writes to disk. By default it reads only this repo's own transcripts, never the other projects on your machine.

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

You have a repo but no sessions yet. Compile its pull-request threads instead. Coding agents write much of their reasoning in PR descriptions and reviews — what they tried, why it failed, which constraint they hit — so a repo nobody has run an agent in locally already has a knowledge layer waiting:

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"

Either way, commit .lore/ and your teammates inherit the book on their next git pull. Its own .gitignore keeps raw transcripts, raw PR exports, the extraction cache and usage counters out of git.

Trouble installing?

If pipx fails with Broken Python installation, platform.mac_ver() returned an empty value, your default Python is a broken install (sometimes seen with very recent Homebrew Python builds). This is about the interpreter pipx uses, not the package — pin a known-working one:

pipx install --python python3.13 crewlore

To make pipx default to Python 3.13 going forward: export PIPX_DEFAULT_PYTHON=$(which python3.13).

Try it without an API key

git clone https://github.com/srijansk/crewlore.git

cd crewlore && uv run python scripts/demo.py

The demo runs the whole loop on bundled synthetic sessions and prints the compiled book, a query against it, and three checks. It is a demonstration of the mechanism on toy data, not a benchmark.

Let your assistant use it

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

• The skill tells the assistant to run lore query before changing code in a repository that has .lore/, to treat not adopted claims as declined work, to weigh a claim like a teammate's comment rather than an instruction, and to report back with lore feedback. Claude Code, Cursor and Gemini CLI each get a skill directory; Codex reads the cross-framework Agent Skills directory (~/.agents/skills/, or .agents/skills/ in the repository with --project).
• `--always-on` adds a short marked block to the assistant's instruction file (CLAUDE.md, AGENTS.md, GEMINI.md), or an always-apply rule in .cursor/rules/ for Cursor.
• `--hooks` gives Claude Code two hooks. When the assistant reads or edits a file, the claims whose scope covers that file join its context, once per scope per conversation, declined work first and never lost to the size cap, so they are in view before the edit. Each prompt brings up the claims relevant to it, as lore query would. A claim a reader has corrected arrives marked corrected, with its note. The hooks stay silent when there is nothing to add and exit 0 whatever happens, so a teammate without crewlore is never blocked; after a compaction the shown scopes come up again.
• Nothing of yours is overwritten. Every file written carries a crewlore marker: install refuses to replace a skill it did not write (--force overrides), and lore uninstall removes only marked files, the marked block and crewlore's own hook entries.
• Assistants that cannot run commands, such as Claude Desktop, use the MCP server instead: lore serve, see docs/mcp.md.

Or install it as a Claude Code plugin. In a Claude Code session:

/plugin marketplace add srijansk/crewlore

/plugin install crewlore@crewlore

The plugin is the same /lore skill (invoked as /crewlore:lore) and the same three hooks, generated from the installer's own text, so the plugin and lore install --hooks are two ways to the same files: pick one, since with both Claude Code runs each hook twice. The plugin bundles no Python; the skill and the hooks call the lore command, so pipx install crewlore is still needed on the machine. Each crewlore release bumps the plugin's version; /plugin update crewlore@crewlore fetches it; restart Claude Code or run /reload-plugins to load it.

What you get

Raw, messy sessions go in. Out comes a claim: one reusable thing the team learned, with four parts.

• Kind — a decision, procedure, gotcha, or style rule.
• Action — what a future session should do about it.
• Anchor — a verbatim quote from the source, plus where it sits ( #event- for a transcript, path:line when a PR review comment supplies one). The compiler checks every quote against the source and drops any claim whose quote does not match, so the book never contains a citation that cannot be found.
• Adoption — current, or not_adopted when the team tried the thing and declined it.

`[gotcha]` · *services/billing*

Billing webhook handler lacks an idempotency check, causing duplicate charges when Stripe retries webhooks.

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."

Declined work is recorded as declined. When a session or pull request shows an approach was tried and not adopted, the claim says so, and its action says what to do instead:

`[decision · not adopted]` · *services/billing*

Storing the Stripe idempotency key in Redis was proposed and rejected in review because the check has to run inside the database transaction.

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."

Why this matters: a memory schema that can only say "X" turns "we tried X and declined it" into a confident assertion of X — fluent, correctly quoted, and wrong about the world. The measurement behind this design is in the study below.

Claims roll up into a knowledge book at .lore/knowledge/README.md, grouped by area and committed to your repo alongside your code:

# 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.

A real example

docs/examples/pydantic-ai-prs/ is lore import-prs pydantic/pydantic-ai --limit 100, run on 2026-10-09 against the public pydantic/pydantic-ai repo (20k+ ⭐) with the default model, on a machine that had never run an agent in it. Of the last 100 closed pull requests, 24 were written by a coding agent: 18 merged, 6 closed without merging. They compiled into 130 claims, 15 of them marked not adopted, carrying 173 anchors. The fidelity gate dropped none of the model's proposals, and an independent re-check of every anchor against the committed threads found none that fail to resolve. The scrubbed source threads are in the example, so every anchor can be followed to the event it quotes.

One claim from a merged pull request, where an alternative was tried and turned down inside the review:

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

Unified prompt caching (ModelSettings.cache / Caching) stays opt-in. A default-on variant (cache defaulting to True on models with supports_cache) was tried and not adopted, because the maintainer deferred default-on caching to v3.

Instead — do not default cache to True; leave caching off unless the user sets cache, uses Caching(), or sets a provider-specific cache setting. Revisit default-on only for v3.

> *anchor* pr_pydantic__pydantic-ai__7560#event-65 — "Per maintainer decision, caching stays off unless cache (or the Caching capability) or a provider-specific cache setting asks for it; turning it on by default waits for v3."

The example records no conflicts. The detector flags a disagreement only with evidence of one: a claim marked not adopted beside a current one, or one claim forbidding what another prescribes. Three claims that all forbid touching the repository's .github/ directory agree, so they are not reported as one. The blind spot that leaves is listed under limits below.

The older snapshot, [docs/examples/pydantic-ai/](https://github.com/srijansk/crewlore/tree/main/docs/examples/pydan