# Burr

Burr is local debugging memory for coding agents. No account, hosted memory, or outbound telemetry.

## Install

Requires Node.js 22.12+.

Global: install `burr-memory@latest` globally, then run `burr global`.
Project: install `burr-memory@latest` as a dev dependency, then run the installed `burr init` binary.
The package is named `burr-memory`; its executable is `burr`.

## Updates

Reinstall with @latest using the original installation method, then rerun burr global or the installed burr init. Reload the host and review new Codex hooks in /hooks. Pi needs its package extension loaded. burr doctor checks storage, not host registration; inspect a runtime run with burr stats or burr dashboard after using a tool through a supported adapter.

## Debugging workflow

1. Search shared playbooks before guessing a fix: `burr search "error text"`.
2. Capture a reusable failure: `burr capture --error "error text" --command "test command"`.
3. Run verification, then save a fix: `burr resolve --error "..." --cause "..." --fix "..." --verify "command and result"`.
4. Inspect CLI usage with `burr audit`. Use `burr on`, `burr strict`, or `burr off` for project mode.

The caller is responsible for truthful verification. Burr does not execute the verification command. Strict mode instructs the agent to search first; it is not a universal edit blocker.

## Storage

- `~/.burr/memory/playbooks/`: CLI Markdown playbooks and runtime Markdown exports.
- `~/.burr/memory/signals/`: reusable CLI failures.
- `~/.burr/memory/knowledge/`: runtime knowledge, playbook records, repository rules, and avoid lessons.
- `~/.burr/memory/tool-strategies/`: runtime strategies.
- `~/.burr/candidates/`, `archive/`, `runs/`, `metrics/`: runtime records.
- `<project>/.burr/`: project config, instructions, generated skills, and CLI usage.

`burr init` appends `.burr/` to the project gitignore. Preserve team-owned editor configuration; decide separately which generated host copies to ignore.

## Hosts

Claude Code uses `/burr-*`, Codex uses `@burr-*`, and Pi uses `/skill:burr-*`. OpenCode loads the bundled plugin. Pi runtime events require the package extension; project initialization copies skills only. Cursor and Windsurf receive project rules through `burr init`; `burr global` does not activate their global rules. Existing user instructions and edited host files are preserved.

## Runtime API

```typescript
import { LoopDetector } from "burr-memory/api";

const detector = new LoopDetector({ autoRecord: false });
const args = { cmd: "npm test" };
const check = detector.evaluateAction("run_command", args);
if (check.blocked) {
  console.warn(check.reasons, check.suggestedAction);
} else {
  // Execute the tool, then record its actual output and status.
  detector.recordAction("run_command", args, "test output", "completed");
}
```

The root import is the OpenCode plugin. Codex `init` and `global` install native SessionStart, PreToolUse, PostToolUse, and SessionEnd hooks; review new hooks in `/hooks`. `/codex` also exports lifecycle functions for custom integrations, whose callers must invoke them and honor blocking decisions. Defaults warn at 50; scores of 70 or more can block repeated failed executions, while productive repeats remain warnings; scores are heuristics, not proof that an action is wrong.

## Maintenance and diagnostics

`burr stats`, `burr compare <run-a> <run-b>`, and `burr dashboard --port 4747` inspect runtime data. CLI Markdown search and runtime JSON retrieval are separate paths. `burr memory list`, `burr memory inspect <id>`, and `burr memory summary` inspect runtime memories.

Run `burr memory prune` explicitly to mark old memories stale, archive them, and delete expired run history. Defaults are 30 days, 60 days, and seven days respectively. No background scheduler or fixed total storage cap is supplied. `burr doctor` reports directory health and storage counts; it cannot certify host hook registration.

## Evidence

The four-session test in `test/benchmark.test.ts` uses scripted inputs and supplied tool outputs. It is regression coverage, not an independent measurement of agent speed or token savings.

## Links

- Source: https://github.com/sansynx/burr-memory
- Website: https://sansynx.github.io/burr-site/

Codex init/global installs native SessionStart, PreToolUse, PostToolUse, and SessionEnd hooks. Review new hooks in /hooks. Global registration respects CODEX_HOME. Native command execution and denial were tested on Codex CLI 0.160.0 with an isolated local provider.