Docs / Shared memory
Handoffs
When an agent writes a handoff, what goes in it, and how it becomes a memory card.
A handoff is a short note one agent leaves for the next. It is a file in a per-tool inbox such as .claude/memory-handoffs/ or .codex/memory-handoffs/.
When an agent writes one
The agent decides, following the AGENTS.md that brigadestack init generates. It writes a handoff only for knowledge that the repository, git history or an existing card does not already hold: a root cause, a decision with its reason, a new operational fact or a stated preference. It searches memory first with brigadestack memory search. If the session produced nothing like that, it ends with one line, Nothing durable: <reason>, and writes no file.
What goes in it
A handoff has a title, a summary, facts, and any evidence. It also names an action:
create-cardmakes a new memory card. The card text goes in--content-file, and it must start with YAML frontmatter (topic,category,tags).no-cardappends the note to a document such as.learnings/LEARNINGS.md, picked with--target-document.
brigadestack handoff draft --target . --inbox claude --type gotcha \
--title "Retry test raced the fake clock" \
--summary "The test advanced the fake clock before the timer was registered." \
--fact "Register the timer before advancing the clock." \
--action create-card --target-card retry-test-fake-clock.md \
--content-file ~/card.md
handoff draft creates the file with mode 0600, so only your user can read it, and runs a lint check. It refuses and writes nothing if the card text has no frontmatter.
How it becomes memory
brigadestack ingest stages handoffs by default. Two flags make it write them out:
--promote-cardsturns safecreate-cardandupdate-cardhandoffs into cards undermemory/cards/.--route-documentsappends targeted updates toTOOLS.md,USER.md,rules/and.learnings/.
Ambiguous material goes to a review inbox instead of being trusted.
Run it in the background
brigadestack care install --target . writes the default set of scheduled jobs for the repo. One of them runs ingest --promote-cards --route-documents every 30 minutes, after a strict lint of the inboxes. The jobs run as runbooks, which are part of the extras commands in 0.31.0, so turn those on first. On Linux the jobs are systemd user timers. Reload systemd, then start the ingest timer by the name care install printed:
brigadestack extras on
brigadestack care install --target .
systemctl --user daemon-reload
systemctl --user enable --now brigade-care-<id>-ingest-sweep.timer
<id> is the same in every unit name the command lists. The command’s own closing hint starts only the first timer, daily-care, so start ingest-sweep by name. On macOS it writes launchd jobs, and on Windows it prints a Task Scheduler plan. brigadestack care status --target . shows when each job last ran.
Review the queue
brigadestack handoff list
brigadestack handoff show <handoff-id-or-path>
brigadestack handoff archive <handoff-id-or-path>
brigadestack handoff archive --all-reviewed
list prints each draft’s id, status, lint result, ingest state, target and path. The recommended action and stale age are in list --json. archive moves a draft to .brigade/handoffs/archive/ and records why. --all-reviewed archives only drafts that pass lint. brigadestack handoff runs and brigadestack handoff run-show <run-id> read the ingest run records that an ingestor leaves under .brigade/handoffs/ingest-runs/. brigadestack handoff reconcile writes one from the last run log. These commands only report. They do not run the ingester or edit cards.
Handoffs from scanner imports
A reviewed scanner import that is a decision, preference, link, command, finding or incident can become a handoff draft:
brigadestack work import plan-handoff <import-id>
brigadestack work import promote-handoff <import-id>
plan-handoff previews the target, type, inbox and blockers. promote-handoff writes the draft, lints it, and only then marks the import promoted. It writes a local draft and leaves cards alone.
Raw chat fields such as raw_text, messages, quotes and transcript are rejected. Unsafe URLs, tokens, private paths and ids are redacted before the draft is written.
Task imports use brigadestack work import promote instead. The handoff command page lists every option.