How the room works, no magic.
What happens on your machine when you talk to your agents, told for anyone and with the detail a developer looks for. Every claim on this page matches code in the repository, and that code has its test.
The map
Everything happens on your machine.
MADRE is a small server that runs on your machine. Your browser talks to it, it talks to the agents, and each agent talks to its provider with your account.
Your machine
- Your browserThe room, at 127.0.0.1
- MADREThe log, the memory and the permissions
- The agentsCodex, Claude Code, Gemini CLI and OpenCode, each in its own box
Outside
The log
One source of truth.
Each project has its room, and everything that happens in it is written to a file, one line per thing. Nothing is erased: things are only added.
It rebuilds itself. If MADRE restarts, or you open the room from another editor (IDE), the conversation is rebuilt from that file.
No collisions. If you open the same room in two editors, they never step on each other: each write waits its turn with a lock on disk.
Handoffs that stay. When the answering agent changes, the room records from whom to whom and which stretch of the conversation was handed over.
Live, in every tab. Open pages are fed from the log: what another process writes arrives too, and on reconnect they pick up where they left off.
GHOST leaves no trace. Its events reach the open pages and never the log.
Clear limits. Each agent receives up to 16,000 characters of conversation, most recent first. A message over 20,000 is rejected without calling the agent.
The memory
What is said gets distilled.
The memory is built from that file, so if it is lost it is built again. An “archivist” agent sums up what matters as notes, and each turn receives the ones it needs.
It is recorded
Every message outside GHOST enters the index with its number.
It is distilled
Every few exchanges, or when idle, the archivist writes up to five typed notes: a decision, a fact, a preference or a question.
It is searched
When the conversation no longer fits, each turn receives, within the same budget, the notes and exchanges that match the request.
It is linked
Notes that arrive together again and again get linked: bring one, and the other comes too.
The cheapest archivist. In this order: Ollama, Gemini, OpenCode, Codex, Claude. One call per batch, and never during a turn.
No waiting. Search by meaning (embeddings) is prepared in the background: a turn never waits for it.
Measured against a control. MU/TH/UR tests whether the archive answers, whether it contradicts itself and whether the local model is ready. The first run scored 30 of 30; against a control, 40%. A number that actually means something.
The agents
Each agent in its own box.
Each agent runs separately, in an isolated space that only has the sessions you already had. If it stops answering in time, MADRE stops it completely, along with anything it opened.
- Codex
- Read-only for questions; with scoped write access in CREATE and over the project in CONTROL.
- Claude Code
- Local read tools, sessions that do not persist, and only MADRE’s MCP servers.
- Gemini CLI
- Plan mode and a temporary read-only policy, with a home of its own: its tokens yes; its hooks, extensions and memory, no.
- OpenCode
- Permissions injected on every run, without touching your global config.
- @madre
- Not a separate program: a local Ollama model that receives the recent conversation and what the memory recalls, never the document the other agents receive.
--sandbox read-only, and environment variables by name only. MADRE 0.4.0 running locally · Sep 26 2026CONTROL, inside
Snapshot, turn, diff, UNDO.
How an agent edits your project without you losing anything.
Snapshot
A real commit under
refs/madre/checkpoints/, including untracked files and respecting.gitignore. Your branch, index and stash are untouched.Turn
Protected files are read-only while the agent works.
Diff
Comparing against the snapshot gives the change list; any write to a forbidden zone is reverted and named.
UNDO
Restores the whole snapshot.
CREATE takes the same snapshot, without exclusivity: several turns can run at once. What is new stays; what already existed and changed is restored.
Usage limits
One meter per agent, no guessing.
When the provider publishes it. Codex leaves its usage windows on your disk and MADRE reads them, with no network. Claude Code publishes its usage and MADRE asks for it only if you turn that on.
When it does not. Gemini and OpenCode show a local window: a soft budget of 500,000 tokens per agent over a rolling five hours.
Warnings in time. At 80, 90 and 100% the room warns you and suggests another agent. MADRE never infers the provider’s quota from its own counts.
When things break
Built to recover.
A startup that heals. If MADRE stopped mid-turn, on its way back it records that turn as failed instead of leaving it hanging.
A clean shutdown. With Ctrl+C it interrupts running agents, tells the open pages and closes.
Every plan ends. Steps run in sequence and delegates do not delegate. STOPALL cuts anything.
Tested before it ships. No test calls a model. Before every release it is packed, installed in an empty folder and the server is started.