ES Install

What MADRE does on your computer, piece by piece.

I’ll walk you through what happens on your computer every time you talk to your agents. Everything I say here comes from code in the repository, and that code has its test.

Read INTERNALS.md

Based on docs/INTERNALS.md · MADRE 1.1.3

In short

  • MADRE is a small server on your computer: your browser talks to MADRE, MADRE to your agents and each agent to its provider, with your account.
  • Everything that happens in a project is written to one file, a line for each thing. Nothing is deleted, and the memory is built from there.
  • Each agent works in a box of its own, only with the sessions you already had. If it does not answer in time, MADRE stops it.
  • Before an agent edits at #3, MADRE keeps a copy, and Undo takes everything back.

The map

What runs on your computer and what doesn’t.

MADRE is a tiny server that runs on your computer. Your browser talks to MADRE, MADRE talks to the agents, and each agent talks to its provider using your account. On Windows, all of this runs inside WSL2, and your Windows browser opens it just the same.

Your computer

  1. Your browserYour projects, at 127.0.0.1
  2. MADREThe log, the memory and the permissions
  3. The agentsCodex, Claude Code, Gemini CLI, Cursor and OpenCode, each in its own box
@madre · optionalA local model with Ollama. It never leaves your computer.

Outside

The providersOpenAI, Anthropic, Google, Cursor and OpenCode’s, with your account and your limits

The log

Everything that happens in a project goes into a file.

Each project has its own. What happens there gets written to that file, one line per thing that happens (an event). New stuff goes at the end and nothing gets erased.

  • It rebuilds itself. If MADRE restarts, or you open the project from another editor (IDE), the conversation gets put back together from that file.

  • Two editors at once. If you open the same project in two editors, each write waits its turn thanks to a lock on disk, so neither one overwrites the other.

  • Handoffs get written down. When a different agent answers, MADRE notes who it passed from and to, and which chunk of the conversation was handed over.

  • Every tab stays current. Open pages read from the log, so they also see what another process writes. If they disconnect, they pick up where they left off.

  • #0 Incognito leaves no trace. What happens in Incognito shows up on the open pages, but it never reaches the log.

  • How much each agent gets. Each agent gets up to 16,000 characters of conversation, starting with the most recent. A message over 20,000 gets rejected without even calling the agent.

The memory

Where the memory comes from.

The memory comes from that same file. If it gets lost, it’s rebuilt from there. An “archivist” agent sums up what matters as notes, and each turn gets the ones it needs.

  1. It gets recorded

    Every message that isn’t in Incognito goes into the index with its number.

  2. It gets summed up

    Every so many exchanges, or when things go quiet, the archivist writes up to five notes. Each one has a type: a decision, a fact, a preference or a question.

  3. It gets searched

    When the conversation no longer fits, each turn gets the notes and exchanges that match what you asked for, without going over the same budget.

  4. It gets linked

    Notes that show up together again and again get linked. Bring one, and the other comes too.

MADRE 1.1, “What is sent › What the agent reads”: the document of a turn for @codex in 13 parts (the project, who writes, how to answer, privacy, memory tools, permission mode, recent context…), each with its size and when it goes in.
What the agent reads, part by part. MADRE builds this document on every turn with what it needs from the memory; you see it by touching the core of the Memory map. It is built when you open it and never saved.

  • Who writes the summary. The first one available, in this order: Ollama, Gemini, OpenCode, Codex and Claude. It makes one call per batch and never during a turn.

  • Search doesn’t slow turns down. Search by meaning (embeddings) gets prepared in the background, and no turn sits waiting for it.

  • Measured against a control. Diagnostics checks 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%.

The agents

Each agent works in its own box.

Each agent runs on its own, in an isolated space that only has the sessions you already had. If it doesn’t answer in time, MADRE stops it completely, along with anything it opened.

Codex
Read-only when you’re asking questions. In #2 Create it gets scoped write access, and in #3 Edit, write access over the project.
Claude Code
Local tools for reading, sessions that don’t stick around and, for MCP servers, only MADRE’s.
Gemini CLI
Plan mode and a temporary read-only policy. It runs with a home of its own that brings its tokens, but not its hooks, extensions or memory.
OpenCode
MADRE hands it the permissions on every run, without touching your global config.
@madre
A local Ollama model, not a separate program. It gets the recent conversation and what the memory recalls, but never the document the other agents get.
MADRE 1.1, “What is sent › How it starts”: the exact command MADRE would launch Codex with, with --sandbox read-only and environment variables shown by name only, “set for this turn, not shown”.
How a Codex turn starts. --sandbox read-only, and environment variables by name only.

Edit, inside

What happens when an agent works in #3 Edit.

Before the agent works, MADRE saves a copy. When it’s done, you see what changed and, if you want, you undo it.

  1. Copy

    A real commit, saved under refs/madre/checkpoints/. It includes the files git doesn’t track and respects your .gitignore. Your branch, index and stash stay untouched.

  2. Turn

    While the agent works, protected files are read-only.

  3. Changes

    It gets compared with the copy and you get a list of what changed. If the agent wrote somewhere it shouldn’t (a forbidden zone), that gets reverted and MADRE tells you.

  4. Undo

    Puts the whole project back the way it was in the copy.

#2 Create saves the copy too, but there several agents can work at once. What’s new stays. What already existed and changed gets restored.

Usage limits

How much of each plan you have left.

  • If the provider publishes it. Codex leaves its usage windows on your disk and MADRE reads them right there, with no network. Claude Code publishes its usage, and MADRE asks for it only if you turn that on.

  • If it doesn’t. Gemini and OpenCode show a local window. It’s a soft budget of 500,000 tokens per agent, counted over a rolling five hours.

  • Warnings in time. At 80, 90 and 100%, MADRE warns you and suggests another agent. MADRE never makes up the provider’s quota from its own counts.

When something fails

What happens when something breaks.

  • Half-finished turns. If MADRE stopped in the middle of a turn, when it comes back it marks that turn as failed instead of leaving it hanging.

  • Closing with Ctrl+C. MADRE stops the agents that are working, lets the open pages know and shuts down.

  • Plans always end. Steps run one after another, and an agent that got work delegated to it can’t delegate. STOPALL stops whatever’s running.

  • Tests before every release. No test calls a model. Before every release, MADRE gets packed, installed in an empty folder and the server gets started.

Open MADRE in your project.

npx @jossuealcala/madre

Back to MADRE