Search BrigadeStack

Search BrigadeStack pages and docs.

BrigadeStack
Menu
Docs menu

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.

  1. A sessionin any agent tool
  2. writes a handoff
    Handoffin that tool’s inbox
  3. ingest, every 30 min
    Memory cardreviewed and kept
  4. recall at start
    Next 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.

This checkoutreads and publishes
Second checkoutreads
The backend scope repo:me/my-app
  • retry-test-fake-clockrev 5
  • release-checklistrev 2
  • ci-runner-cacherev 1
Another machinereads and publishes
Cloud agentreads 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.

Card retry-test-fake-clock is at rev 4

  1. Agent Aedit of rev 4saved as rev 5
  2. 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.

AgentSession startEach promptReplies it already asks for
Claude CodeYesYesNo
CodexNoNoNo
Cloud agentsNoNoYes
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.

  • 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 push publishes local cards to the backend. No scheduled job runs it.

Turn on shared memory covers setup. Handoffs covers starting the ingest job.