Docs / Shared memory
How shared memory works
Memory starts in the repo. With the backend it is shared with no single owner, and it reaches other machines and cloud agents.
An agent that learns something leaves a handoff. A background job turns safe handoffs into memory cards every 30 minutes. The next Claude Code session starts with the cards that match its work, and any other agent tool finds them with memory search.
- A sessionin any agent tool
- writes a handoffHandoffin that tool’s inbox
- ingest, every 30 minMemory cardreviewed and kept
- recall at startNext sessionin any agent tool
It leaves its own handoff, and the loop runs again.
On one machine the cards live in the repo under memory/cards/, as the quickstart shows. The rest of this page is about what changes when the backend runs.
Hosted by the backend
With the backend running, cards are stored there instead of only in one repo. Any agent that has been given access can write to a scope and read from it. A scope names what the cards are about, for example one repository. A second checkout, another machine or a cloud agent reads the same cards through the backend.
- retry-test-fake-clockrev 5
- release-checklistrev 2
- ci-runner-cacherev 1
There is no single owner. No one agent tool or workspace holds the real copy and the rest hand notes to it. init still prints a memory owner line in 0.31.0.
A card keeps a revision number. A writer names the revision it edited, and the backend refuses the write if the card has changed since, so one agent cannot overwrite another’s edit unseen.
Card retry-test-fake-clock is at rev 4
- Agent Aedit of rev 4saved as rev 5
- Agent Bedit of rev 4refused, the card is at rev 5
Cards are stored as plain text on the backend, inside your own network. Do not put secrets in a card.
Reaching agents without them asking
An agent should not have to remember to look. BrigadeStack pushes memory in through calls the agent already makes.
| Agent | Session start | Each prompt | Replies it already asks for |
|---|---|---|---|
| Yes | Yes | No | |
| No | No | No | |
| Cloud agents | No | No | Yes |
memory search.- Claude Code hooks run
memory recallat session start and on each prompt, and show the title, tags and path of the top matches. A repo-level install reads the backend this way once a recall target is configured. - Codex has no recall hook in 0.31.0. It gets memory through its handoff inbox and through
memory search, which theAGENTS.mdthatinitwrote tells it to run before it writes a handoff. - Cloud agents get the top matches inside responses they already request, such as the digest and inbox views, so they need no extra tool.
Search works the same way for you. In a second checkout, brigadestack memory search "fake clock" prints matches tagged [hub], and brigadestack memory hub card <card-id> prints the card body. Search is keyword based by default in 0.31.0.
What runs in the background
brigadestack care install writes the scheduled jobs for a repo: systemd timers on Linux and launchd jobs on macOS. On Windows it prints a Task Scheduler plan with the schtasks commands, and you create the tasks yourself. Once the jobs are started, ingest runs every 30 minutes and turns safe handoffs into cards, and a memory check runs each morning.
- Ingest, every 30 minutes: 48 runs a day
- Memory check, daily at 06:15
- Recall needs no job. The Claude Code hooks run it when a session starts and on each prompt.
- Writes from agents that nobody has reviewed wait on the backend until a review decision or a policy promotes them, so one bad note does not spread to every agent.
- One step is still a command in 0.31.0:
brigadestack memory hub pushpublishes local cards to the backend. No scheduled job runs it.
Turn on shared memory covers setup. Handoffs covers starting the ingest job.