# How shared memory works

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`.

Figure: how a note becomes memory.

1. A session in any agent tool writes a handoff to that tool’s inbox.
2. Ingest runs every 30 minutes and turns safe handoffs into memory cards.
3. The next session, in any agent tool, gets matching cards through recall at start.
4. That session leaves its own handoff, and the loop runs again.

On one machine the cards live in the repo under `memory/cards/`, as the [quickstart](/docs/getting-started/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.

Figure: the backend holds the cards for a scope, for example `repo:me/my-app`.

- This checkout reads and publishes.
- A second checkout reads.
- Another machine reads and publishes.
- A cloud agent reads and writes.

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.

Figure: card `retry-test-fake-clock` is at rev 4.

1. Agent A sends an edit of rev 4. It is saved as rev 5.
2. Agent B sends an edit of rev 4. It is refused, because 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 |
|---|---|---|---|
| Claude Code | yes | yes | no |
| Codex | no | no | no |
| Cloud agents | no | no | yes |

On a repo install the hooks need a recall target set first. Codex has no recall hook: its agent runs `memory search`.

- Claude Code hooks run `memory recall` at 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 the `AGENTS.md` that `init` wrote 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.

Figure: one day after `care install`.

- Ingest runs every 30 minutes, 48 times a day.
- The memory check runs once a day 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 push` publishes local cards to the backend. No scheduled job runs it.

[Turn on shared memory](/docs/guides/fleet-hub#turn-on-shared-memory) covers setup. [Handoffs](/docs/guides/handoffs#run-it-in-the-background) covers starting the ingest job.