# Burr

Burr is local debugging memory for coding agents on this machine. A burr is
a seed that hooks on and rides with the next passerby — the next session,
the next project, the next agent.

Playbooks and signals live in **`~/.burr/memory/`**, not in one repo. That
way a compacted session or an agent in another project can pick up the same
fix. The current project's `.burr/` holds config, usage, and host copies only.

Read `.burr/config.json`. Mode is `on` (default), `strict`, or `off`.
If `off`, do nothing Burr-related.

Codex: `burr init` or `burr global` registers native session and tool hooks.
Review new definitions in `/hooks`; do not bypass the host trust review.

## Do this

1. Before a non-trivial fix, search `~/.burr/memory` (playbooks and signals).
   Also look at leftover files in this project's `.burr/memory` if any exist.
   In `strict` mode, do not patch until that search has run.
2. If the failure is reusable beyond this machine and this moment, capture it
   as a signal under `~/.burr/memory/signals/`.
3. After a fix is verified, write a playbook under `~/.burr/memory/playbooks/`.
   No playbook without real verification. Never write playbooks or signals
   into another repo.
4. Redact secrets, tokens, private keys, JWTs, home paths, emails, and raw
   credentials before any disk write. Never store source trees, `.env` files,
   or customer data.
5. Append one JSON line to this project's `.burr/usage.jsonl` for search, hit,
   miss, capture, resolve, promote, or discard.
6. Follow this project's existing instructions first. Burr does not override them.

## Do not

- Invent extra Burr commands.
- Call a remote memory API.
- Edit AGENTS.md, CLAUDE.md, or foreign rule files to "enable" Burr.
- Mix one project's source tree or `.env` into memory.
