Burr / Documentation

Start with a useful memory.

Save a verified fix. Find it in your next debugging session. Burr keeps the records on your machine.

Install

Requires Node.js 22.12+. Install the CLI, then set up the project you work in.

npm install -g burr-memory@latest
cd your-project
burr init

Use burr global for supported user-level integrations. Review Codex hooks in /hooks. See agent setup for the differences.

npm install -D burr-memory@latest
npm exec -- burr init
npm exec -- burr search "your error"

Use it on a real failure

burr search "response.users is undefined"
burr capture --error "response.users is undefined" --why "API schema changed"
# Fix the code and run your project's checks.
burr resolve --error "response.users is undefined" --cause "users moved into data" --fix "Read response.data.users" --verify "npm test: 12 passed, 0 failed"
burr audit

Burr checks the verification text; it does not run the command for you. Supply the actual result.

Update. Reconnect. Check.

Updates are explicit. Use the same installation method you started with, then regenerate the integration so it points at the current runtime.

npm install -g burr-memory@latest
burr global
burr doctor

# In the project that installed Burr locally
npm install -D burr-memory@latest
npm exec -- burr init
npm exec -- burr doctor

# Pi extension installation
pi install npm:burr-memory@latest

Restart or reload your agent after installation. Review Codex hooks in /hooks. Confirm that OpenCode loaded its plugin or Pi loaded its extension. A successful burr doctor checks local storage; it does not prove that a host registered its hooks.

Run a tool through a supported adapter, then inspect burr stats or burr dashboard for a recorded run. Skills-only integrations rely on the agent invoking Burr commands. See the support matrix before expecting automatic observation.

One machine. Shared memory.

Playbooks are available across your local projects. Each project keeps its own configuration and usage.

~/.burr/
  memory/playbooks/        Markdown fixes
  memory/signals/          Captured failures
  memory/knowledge/       Structured runtime lessons
  memory/tool-strategies/  Tool strategies
  candidates/             Proposed lessons
  archive/                Retired lessons
  runs/                   Tool histories
  metrics/                Runtime events

<project>/.burr/           Config, instructions, generated skills, usage

CLI search reads Markdown. Runtime retrieval reads structured lessons and checks available scope. This is local storage, not cloud sync or team sharing.

Keep local records out of Git.

burr init adds .burr/ to your gitignore. Review generated host files separately. Preserve team-owned rules, and do not commit debugging records containing private context.

Catch repeated failures.

Loaded runtime adapters record tool outcomes and check proposed actions for repetition, cycles, and stalled output.

The default score warns at 50. Scores of 70 or more can block repeated failed execution; productive repeats remain warnings. These are heuristics, so inspect the reasons before changing your workflow.

Skills and editor rules do not intercept tools. A custom integration must call the runtime and honor its decision. burr off disables runtime guidance for the project; burr strict adds search-first instructions, not a universal edit block.

Read the detector details

Keep the useful lessons.

Runtime admission checks evidence and scope before promoting or merging a lesson. Confirmed reuse adjusts confidence; replayed session evidence does not count twice. Archived runtime lessons are removed from active search exports.

Run burr memory prune to apply retention. Defaults mark unused runtime lessons stale after 30 days, archive after 60, and remove run histories after seven days. CLI signals and usage logs have no automatic expiry or total storage cap.

Local by design.

Burr makes no outbound network requests after installation. Your agent's model connection is separate. Known secret patterns are redacted before storage, but arbitrary sensitive data may still remain. Do not submit credentials, customer data, or full source trees.

Guarded writes reject path escapes and linked paths. Retrieved lessons are untrusted historical evidence, not instructions to override your current task. The local dashboard has no account login and binds to 127.0.0.1.

Choose your agent.

Choose the setup for your editor. Skills guide the agent; loaded runtime adapters can also observe tool outcomes.

Native checks passed on Codex 0.160.0, Pi 0.80.10 and 1.0.0, and OpenCode 1.18.34. Codex and Pi checks cover tool behavior; OpenCode's native check covers discovery, with callbacks covered separately. These are version-specific checks, not a promise that every agent or future release works unchanged.

Everyday commands.

Find saved fixes, inspect local activity, and manage runtime lessons.

burr status                 # Current project mode
burr search "error text"     # Find a saved fix
burr audit                  # CLI usage
burr stats                  # Runtime observations
burr doctor                 # Local storage checks
burr dashboard              # Local metrics UI
burr memory list            # Runtime lessons
burr memory prune           # Apply retention
burr off                    # Disable project runtime guidance

For project installations, prefix commands with npm exec --. burr doctor checks storage, not whether your editor loaded its integration.

Bring your own agent.

Import from burr-memory/api. The root import exports the OpenCode plugin.

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 your tool; record its actual output and status.
  detector.recordAction("run_command", args, "12 passed", "completed");
}

This in-memory example does not execute a tool. The /codex lifecycle API adds persistence, retrieval, and reflection when your host calls it with real outcomes. Session completion is not verification.

A short reference for agents.

Read llms.txt for commands, storage, and integration boundaries in plain text.