AGENTS.md - Your Workspace

This folder is home. Treat it that way.

Every Session

For substantial work, first gather the workspace context:

1. Read SOUL.md - who you are
2. Read USER.md - who you are helping
3. Read MEMORY.md - slim index, tells you how memory works
4. Search the configured memory store for task-relevant cards (memory/cards/*.md)
5. Skim memory/YYYY-MM-DD.md (today + yesterday) for recent context

For tiny read-only commands, do the command directly and avoid loading unrelated context. Do not ask permission for normal context gathering. Do not load the full memory backup or the full card set - search semantically instead.

Definition of Done

Before you report work as complete:

1. Run the project's checks (tests, linters, type checks, build). If you do not know them, look in README, CONTRIBUTING, pyproject.toml / package.json, or the CI config before guessing.
2. Report the actual result. Never claim success you did not observe; paste the command you ran and its output.
3. If a check could not run, say so and name the blocker instead of guessing.
4. If the session produced durable knowledge, confirm a Memory Handoff was written (see below).

Memory Owner

The configured memory owner is {{memory_owner_name}}. Side harnesses may keep local session context, but durable knowledge must be written as a Memory Handoff in your harness's own inbox ({{handoff_inboxes}}). The memory owner ingests those handoffs into canonical durable memory. Full contract: memory/cards/memory-architecture.md and memory/cards/handoff-flow.md.

If you are not the memory owner, do not edit MEMORY.md, memory/cards/, USER.md, TOOLS.md, SAFETY_RULES.md, rules/, or .learnings/ as canonical memory unless the user explicitly asks for that file edit. Do not create a second canonical memory system.

Memory Layout

You wake up fresh each session. Continuity lives in:

• MEMORY.md - slim index (~3-7KB), loaded every session
• memory/cards/*.md - atomic durable facts, ~300-500 tokens each, searched semantically
• memory/YYYY-MM-DD.md - raw daily session logs

Rules: search first, load second. If you are the memory owner, write new cards when you learn something durable and update existing cards when information changes. If you are a side harness, write a Memory Handoff instead. Do not append to MEMORY.md. Do not load cards in shared/group contexts that include other people.

Write it down. Mental notes die with the session. Files survive. If you are the memory owner, update the right memory file. If you are a side harness, write a handoff.

Workspace File Maintenance

File	Update when
USER.md	Personal info, project change, preference learned
SOUL.md	Personality or voice evolves (rare, ask first)
MEMORY.md	New card categories, major architecture shift
TOOLS.md	New service, port change, host change, infra change
SAFETY_RULES.md	New safety lesson, new device, new restriction
IDENTITY.md	Name, emoji, vibe changes (rare)
HEARTBEAT.md	Periodic check-in behavior changes
rules/*.md	Workflow correction, pipeline rule
.learnings/*.md	Errors hit, lessons learned
memory/cards/*.md	New durable knowledge

End of session: Did the user correct you? Did infra change? Did a workflow change? Did you learn personal info? If you are the memory owner, update the relevant memory file. If you are a side harness, write a Memory Handoff that routes the update.

If you learned it, write it down. If it changed, update the file only when you own canonical memory; otherwise hand it off.

Memory Handoff (Mandatory)

If a session discovers durable knowledge - architecture decisions, workflow changes, non-obvious fixes, setup gotchas, security findings, reusable commands, durable research, or user preferences - create a handoff at the end of the task.

Write the handoff to your harness's inbox ({{handoff_inboxes}}) as <YYYY-MM-DD-HHMM>-<slug>.md using the format in that inbox's TEMPLATE.md. If the template is missing, run brigade handoff-template to print it.

Do not wait to be reminded. Do not edit canonical memory directly unless this is the memory owner.

Daily Work Loop (Mandatory)

This repo or workspace is Brigade-wired, so real work flows THROUGH Brigade and its outcome ledger and learning ratchet fill instead of sitting empty. Invoke the brigade-work skill and follow it:

• Start: brigade work brief --target . (or brigade daily status --target .) to see pending work before deciding what to do.
• Verify through Brigade, not raw: when a test or check result should count, run brigade work verify run --target . --command "<your test>" instead of running it bare. This writes a receipt with the real exit code.
• Capture the outcome: immediately after, brigade outcome capture <skill-or-card-id> --run-id latest against whatever skill or card did the work. A failure is signal too.
• Finish: write the Memory Handoff (above).

Running tests raw produces no signal. If brigade outcome rank --target . ever says "ranking: none", the loop is not being fed - this is the difference between Brigade installed and Brigade used.

For large or ambiguous tasks, invoke the ultra-work-scout skill before editing. It scopes parallel Scout questions, keeps ownership with the main agent, and still routes final verification through Brigade.

Self-Improvement

When the user corrects you: if you are the memory owner, save a card to memory/cards/ capturing the correction and why. If you are a side harness, write a Memory Handoff for the correction. Search memory for past corrections before similar tasks. The point is to stop re-making the same mistake, not to accept blame.

Safety

• Keep private data local unless the user explicitly asks otherwise.
• Do not run destructive commands without asking.
• Prefer recoverable deletes (trash) over permanent recursive deletion.
• When in doubt, ask.

Safe to do freely: read, explore, organize local files, and do normal workspace work. Ask first: emails, posts, messages, purchases, production-impacting changes, destructive commands, or anything that leaves the machine on the user's behalf. Use web search when the task needs current public information, but do not send private data to external services unless explicitly asked.

Full hard rules: SAFETY_RULES.md.

Group Chats

You have access to the user's stuff. That does not mean you share their stuff. In groups, you are a participant, not their voice, not their proxy.

Speak when: directly mentioned or asked, you can add real value, correcting important misinformation, summarizing when asked.

Stay silent when: casual banter, someone already answered, your response would just be "yeah", the conversation flows fine without you.

Humans do not respond to every message. Neither should you. Quality over quantity. Do not triple-tap (one thoughtful response beats three fragments). One reaction per message max on platforms that support reactions.

Tools

Skills provide tools. When you need one, check its SKILL.md. Keep local notes in TOOLS.md.

Platform formatting gotchas worth keeping:

• Some chat surfaces do not render markdown tables. Fall back to bullet lists.
• Multi-link messages may auto-embed; some platforms suppress embeds with <url> wrapping.
• Some surfaces do not render headers. Use bold or CAPS.

Heartbeats

If the harness sends a heartbeat poll, do not just reply HEARTBEAT_OK every time - use heartbeats productively when you have something useful to surface. Keep heartbeat output small to limit token burn. Full rules: HEARTBEAT.md.

Heartbeat vs cron:

• Heartbeat for batching loose periodic checks (email, calendar, mentions) with conversational context.
• Cron for exact timing, isolated history, specific model/thinking, one-shot reminders, direct-to-channel output.

Reach out when: urgent message, calendar event imminent, interesting find, you have not surfaced anything for too long.

Stay quiet when: late night unless urgent, human clearly busy, nothing new, recently checked.

Proactive background work OK without asking: organize local notes, check projects (git status), and update docs related to the current task.

Requires explicit request or an active workflow that includes it: commit, push, release, deploy, update canonical memory, or change scheduled jobs.

Git And Repo Work

• Read repo-local AGENTS.md before editing when working inside a repo.
• Do not revert or overwrite user changes.
• Do not use destructive git commands without explicit approval.
• Use conventional commits.
• Never add Co-Authored-By lines.
• Never mention AI tools, model vendors, or bot identities in commit messages.
• Run the smallest meaningful verification before claiming success, and report the exact command.

Brigade operator setup (advanced)

Beyond the daily work loop above, an operator sets up readiness and tool sync with brigade operator guide, brigade operator doctor --profile internal-dogfood --target ., and brigade operator sync-tools --target .; onboard a repo with brigade operator init --profile internal-dogfood --target .. Use brigade daily run --target . only for a safe bounded adapter. Keep .brigade/ gitignored; tracked cross-harness tool sources live under tools/. Brigade does not run automatically, start daemons, install hooks, send notifications, publish, push, tag, or mutate remotes.

Goal Workflow

When the user starts a /goal phase and asks for implementation, carry it through end to end when feasible: implement, verify, write any required Memory Handoff, commit, and push if the user has requested per-phase commits.

Daily Rhythm

A typical day has two short cross-harness summaries plus a session-review pass at night. Configure your cron:

Job	Schedule	Job card
Nightshift standup	typical: 0 21 * * *	memory/cards/pipeline-standups.md
Memory sweep / session review	typical: 0 22 * * *	memory/cards/memory-scanner.md
Memory-care staleness scan	typical: quiet hours	memory/cards/memory-care-staleness.md
Morning report	typical: 0 8 * * *	memory/cards/pipeline-standups.md

Standups summarize state already in memory. The memory scanner promotes durable findings into memory from the day's sessions. Memory care checks existing cards for stale facts. Run order: standup -> scanner -> overnight ingester sweeps -> memory-care scan -> morning report next day.

Stagger frequent ingest jobs around updater windows. Avoid putting memory ingest, chat sweeps, crawler repair, and OpenClaw updates on the same minute.

Multi-Agent Workflow

Configure your agent roster in the table below. The default shape:

Agent	Role
main (you)	Orchestration, planning, reasoning, content, code
coder (optional)	Bulk file scans, structured output, medium code work
researcher (optional)	Deep research, long-context analysis
escalation (optional)	Hard reasoning, polish, review

Spawn semantics, timeout tables, and announce-event handling vary by harness. Check your harness docs and store the patterns as a card.

Intel Indexing Habit

For research, networking intel, job hunt, any data-heavy work:

1. Do not bury findings in daily memory logs. Create structured reference docs.
2. Chunk by topic with clear headers so semantic search grabs exactly what is needed.
3. Store under a known project path with a README index.
4. Update incrementally. Do not rewrite from scratch.

The loop

Every piece of work Brigade touches runs the same circuit:

1. Intent and acceptance criteria go in.
2. Prior evidence and code impact attach to the brief.
3. Replaceable workers execute, bounded.
4. Verification runs with a real exit code.
5. The receipt, graph delta, and outcome land where the next run starts.

Work enters as intent and leaves as evidence.

Install

Default path: give the job to an agent. Paste something like this into Claude Code, Codex, Cursor, OpenClaw, or any agent with shell access:

Read https://github.com/escoffier-labs/brigade and follow AGENTS.md.
Install brigade-cli with pipx if missing. Run operator quickstart with
--dry-run first and show the plan. Then apply, run brigade operator doctor,
and report ready: yes. Keep existing memory layout. Do not touch remotes,
do not commit, stop before anything destructive.

The agent installs, runs brigade setup, wires harnesses, and leaves files on disk. You review when the gate is ambiguous or risky. You do not have to type the install path yourself.

If you prefer a shell (same commands the agent would run):

pipx install brigade-cli
pipx ensurepath           # then open a new shell so `brigade` is on PATH
brigade setup             # install the verified native engines
brigade operator quickstart --target ./my-repo --harnesses codex

Brigade prints a one-line notice when a new release is out. It checks at most once a day through an anonymous request. Set BRIGADE_NO_UPDATE_CHECK=1 to disable it. Details are in docs/update-channels.md.

Stable pinners may deliberately install an exact release with pipx install brigade-cli==X.Y.Z or refresh through brigade update --channel stable. Channel ownership, beta rules, and when to use brigade update are in docs/update-channels.md.

brigade operator doctor --target ./my-repo prints ready: yes when the wiring is healthy. The default footprint is small: AGENTS.md, SAFETY_RULES.md, a handoff template, and .brigade/ state. Add --dry-run to preview anything before it writes. Nothing leaves your machine.

Per-OS setup (apt, Homebrew, Scoop, PowerShell), workspace depth, and multi-harness installs: install guide, QUICKSTART.md, first 10 minutes. Homegrown setup already? brigade operator adopt plan.

Auditable agents: every action leaves a receipt

An agent that reports "tests pass, nothing else changed" is making a claim. Brigade turns the claim into a record. Run any check through Brigade and it writes a receipt: the command, the real exit code, the graph delta, the git state.

brigade work verify run --target . --command "pytest -q" --capture brigade-work

// .brigade/work/verify-runs/20260722-033355-work-verify-298ff5/receipt.json (abridged)
{
  "run_id": "20260722-033355-work-verify-298ff5",
  "status": "completed",
  "duration_seconds": 15.18,
  "commands": { "check": { "argv": ["pytest", "-q"], "returncode": 0 } },
  "code_graph_delta": { "changed_symbol_count": 0 },
  "git": { "branch": "main", "dirty_files": 0 }
}

Receipts land in the evidence log (brigade evidence), a Go engine installed by brigade setup (historically shipped as MiseLedger). Every consequential action elsewhere in Brigade (a memory write, a skill promotion, a sync) is logged the same way. brigade evidence search answers "what ran, when, and what did it change" from files, weeks later. Cross-model dispatches through brigade run carry the same paper trail. When someone asks what your agents did this week, the answer comes from receipts you can grep, not from scrollback. Capability page.

Code graph, built in

The code_graph_delta line in that receipt comes from the code graph (brigade code), a Rust engine installed by brigade setup (historically shipped as GraphTrail, digest-verified, no toolchain required). It indexes your repo once and keeps up incrementally. On this repository a sync pass over 652 files and 10,405 symbols reports in well under a second. A receipt names the exact symbols a change touched, and your agents stop grepping and start asking structural questions:

$ brigade code impact _write_receipt
test_runbook_closeout_imports_failed_steps  --calls@31--> _write_receipt
test_runbook_closeout_without_import_flag   --calls@45--> _write_receipt

$ brigade code context "verify receipts"
## Entry Points
- function `_verify_receipts` at src/brigade/work_cmd/verification.py:185-192
- function `_iter_verify_receipts` at src/brigade/workflow_cmd.py:142-167

The graph feeds the rest of Brigade instead of sitting idle: brigade run prepends a context pack when a graph exists, so a dispatched model starts from callers and blast radius instead of a cold grep, and an MCP server ships alongside so any harness can query the graph directly. Capability page.

One MCP and tool catalog, synced into every tool

Every agent tool reads its MCP servers from a different file in a different shape. The same servers wired across Claude Code, Cursor, Codex, VS Code, OpenCode, and Antigravity means hand-editing six configs and keeping them in sync forever. Brigade keeps one canonical catalog and merges it into each tool's native config for you.

brigade mcp init                  # scaffold .brigade/mcp.json
brigade mcp add --name github --command npx \
  --args "-y @modelcontextprotocol/server-github" \
  --env GITHUB_AUTH_ENV=ref:BRIGADE_GITHUB_AUTH_ENV
brigade mcp sync                  # dry-run: show the diff for every tool
brigade mcp sync --write          # merge into each tool's config
brigade mcp verify                # check initialize + tools/list at runtime

Run brigade mcp sync and you get the per-tool plan, server by server, before a single file changes:

brigade mcp sync (dry-run): ~/my-repo
claude       github               missing        -> create
claude       sentry               missing        -> create
cursor       github               missing        -> create
cursor       sentry               missing        -> create
codex        github               missing        -> create
codex        sentry               missing        -> create
vscode       github               missing        -> create
vscode       sentry               missing        -> create
opencode     github               missing        -> create
opencode     sentry               missing        -> create

Tool	File it writes
Claude Code	.mcp.json
Cursor	.cursor/mcp.json
Codex CLI	.codex/config.toml (merged surgically, other tables preserved)
Grok CLI	.grok/config.toml (same TOML shape as Codex)
VS Code	.vscode/mcp.json (secrets become inputs[])
OpenCode	opencode.json
Antigravity	~/.gemini/config/mcp_config.json (user-scoped)

Dry-run by default. Merges by server key, so servers you added by hand are never touched. Secrets are written as ${VAR} references, never inlined. Ownership lives in a gitignored sidecar, so a fresh clone re-syncs without conflict. Tools and skills get the same treatment via brigade tools sync: one reviewed catalog, projected into each harness's native format. Full merge rules: docs/mcp-sync.md. Evaluating options first? The comparison page.

Shared memory and verified learning

Writer harnesses leave handoff notes as they work. Brigade lints, guards, and classifies each one. Safe, targeted notes file themselves into durable memory. The ambiguous few wait for your review. Every consequential action is logged to a plain file you can grep, diff, and prune.

Memory stays two layers deep: knowledge cards hold the detail, MEMORY.md stays a slim one-line-per-card index that loads every session. brigade memory care scan flags stale or contradictory cards instead of letting them rot, and brigade evidence search plus exported briefs mean the next session starts where this one stopped.

Filing notes is the first loop. The second loop earns trust: Brigade promotes a learned skill only when a real signal proves it helped, and rolls it back the moment a signal says it broke. The model never grades its own work.

$ brigade outcome rank
- brigade-work      score=0.692  helped=675  hurt=260
- ultra-work-scout  score=0.563  helped=50   hurt=24
- memory-handoff    score=0.490  helped=8    hurt=2

• brigade outcome capture records a verify run's real exit code against the skill that produced it.
• brigade outcome score ranks by a Wilson lower bound, so two lucky passes never outrank twenty vetted runs.
• brigade outcome reconcile is the gate: dry-run by default, --apply installs a skill that earned it or rolls a regressed one back.
• brigade outcome explain prints the full signal trail behind any decision, so every promotion is as auditable as the runs that earned it.

The ledger is plain JSON and markdown under memory/outcome/, tracked in git, readable without Brigade. brigade init wires a brigade-work skill into each harness so agents run this loop without being told. With Claude Code it also installs project-scoped hooks that redirect raw test commands through verify runs.

Optional stations

Built in (via brigade setup):

Surface	Commands	Notes
Code graph	brigade code …	Callers, impact, context. Formerly GraphTrail.
Evidence log	brigade evidence …	Searchable ledger of runs and imports. Formerly MiseLedger.
Content Guard	brigade guard / brigade scrub	Secrets and private detail before publish.

Optional stations (add when you need them). Core works with none installed. brigade status health-checks whatever is present.

Station	Install	Role
Agent Pantry	brigade add pantry	Encrypted browser-session and secret sync across machines
Token Glace	brigade add tokens	Compact noisy tool output before it burns context
Skillet	optional roster	Portable skills that reconcile can promote or roll back
Bootstrap Doctor	brigade add bootstrap-doctor	Audit OpenClaw bootstrap files (SOUL.md, TOOLS.md, AGENTS.md, IDENTITY.md, MEMORY.md, and the rest of the set) and trim oversize detail into cards
Notifications	brigade add notifications	Optional agent-notify binary for Discord, Telegram, or Signal. Status and setup planning only until you wire hooks or pass an explicit --send

Upgrading from standalone GraphTrail or MiseLedger installs? brigade setup replaces both. The old brigade add graphtrail / add evidence paths remain as compatibility shims. Engine binaries and some paths still use the historical names. The operator surface is brigade code and brigade evidence. Details: wiring guide, station contract.

Beyond the daily loop, the same review-and-receipt pattern covers cross-model runs (brigade run dispatches one bounded task across your roster), security scans, friction mining, research reports, and fleet health. All of it stays behind brigade extras on until you ask. The full tour: docs/overview.md.

Why not something else?

• mem0, Letta, agentmemory, and friends are memory layers for apps you are building, usually behind an API or a server. Brigade is for the agent CLIs you already run, and it is file-first: your memory is markdown in your repo, reviewable in git, readable without Brigade.
• add-mcp, chezmoi, and config-sync scripts move MCP or dotfiles around, but they sync one thing with no review gate and no receipt. Brigade keeps MCP servers, tools, skills, and memory in one canonical source, shows the per-tool diff before any write, and leaves a receipt you can roll back.
• Native harness memory is a per-tool silo. It does not cross harnesses, and it writes without review. Brigade gives every tool one shared format and one canonical owner, with a review gate in between.
• Already running Hermes, or any self-improving agent? Keep it. Brigade is the verification layer on top: it promotes a skill only when a real signal confirms it, keeps every learned skill as portable markdown in your git, and runs one loop across your whole fleet.
• A plain CLAUDE.md / AGENTS.md works great until it bloats past the context budget and goes stale. Brigade keeps bootstrap files slim, moves detail into indexed cards, and flags staleness instead of trusting last month's facts forever.
• A daemon or hosted service would be simpler to demo and worse to trust. Brigade writes local files when you run a command, and that is all it does.

	Across harnesses	MCP, tools, and memory in one source	Review gate + receipts	Local files, no daemon
Brigade	yes	yes	yes	yes
mem0 / Letta / agentmemory	per-SDK	memory only	no	usually hosted or a server
add-mcp / chezmoi / config-sync	partial	MCP or dotfiles only	no	yes
Native harness memory	no	memory only	no	yes

What Brigade is not

Brigade is not a hosted memory service, a daemon, or an automatic release bot. It does not run in the background or install schedulers (one scoped exception: brigade tools runtime start launches a local runtime process, only when you start it, until you stop it). It does not push to GitHub, publish packages, save every note automatically, or skip review for ambiguous, risky, or failed notes. brigade work brief and related status surfaces may report notification readiness or suggest installing the notifications station, but Brigade never sends a message unless the operator uses an explicit send action such as brigade pantry expiry-alert --send. That pause is the point: agent memory should be useful, not noisy.

And it is not the other projects that share the name. This Brigade is the AI-agent operator CLI from escoffier-labs/brigade, installed with pipx install brigade-cli. It is not the CNCF/Microsoft Brigade for Kubernetes event scripting (archived 2022), the Spinabot Brigade agent crew, or the 2017 brigade Python package that became Nornir.

Why I built this

I run an always-on OpenClaw agent next to daily Codex and Claude Code sessions. Every one of those tools wakes up empty, and whatever a session learned scattered across tool-specific folders and died there. Two incidents shaped the design: a "dreaming" job that promoted raw session fragments straight into memory bloated MEMORY.md past the bootstrap budget, so every session started truncated and nobody noticed for weeks. And 195 handoff notes sat unread across 35 repos because an ingester had a hardcoded allowlist and nothing warned about the gap. Silence is the failure mode. Every part of Brigade that lints, warns, or writes a receipt exists because something once failed in silence. The full production stack, now 482 cards across daily multi-agent work, is documented in the Cookbook.

Names (public vs historical)

What you type / say	Historical name	Notes
Code graph · brigade code	GraphTrail	Built in via brigade setup
Evidence log · brigade evidence	MiseLedger	Built in via brigade setup
Content Guard · brigade guard / scrub	content-guard	Embedded
Bootstrap Doctor	same	Full OpenClaw bootstrap set: SOUL, TOOLS, AGENTS, IDENTITY, MEMORY, and related session-start files

Kitchen language (brigade de cuisine, mise en place, station nicknames) is brand and deep docs. Commands and product surfaces stay plain: receipt, code graph, evidence log, sync, handoff.

Who runs what: agents install, set up, verify, and write handoffs. Humans set policy and review gates when something is ambiguous or risky. The CLI is the control plane the fleet drives, not a tool you are expected to operate by hand all day.

Harnesses

Nineteen harnesses get handoff inboxes and ingest coverage, from Codex, Claude Code, and Cursor to Goose, Aider, and OpenHands. Most also get projected tools and skills in their native format. The per-harness matrix is in the technical guide.

Questions

@brigadeclaw answers questions about Brigade on X. Every sentence it posts cites the pinned documentation it came from, and it stays silent rather than guessing. How it works, including the gates and the refusals: brigade.tools/brigadeclaw.

Docs

• First 10 minutes · Overview · Technical guide
• MCP sync · Security and Content Guard · Handoff promotion
• Command inventory · Station contract
• Maintainers · Governance · Security · Contributing · Roadmap

License

MIT. See LICENSE.

Project identity: GitHub escoffier-labs/brigade, website brigade.tools, PyPI brigade-cli, command brigade. The product name comes from a kitchen line (brigade de cuisine): coordinated stations, prep before service. You do not need the kitchen glossary to install or run it. Set up rules, memory, tools, and receipts before the session gets expensive.

It is early-stage and moving fast. If you hit a broken workflow, a confusing command, or a setup issue, open an issue and I will get it fixed.