DEV Community: MindMux.ai

We have officially OPEN-SOURCED projectbrain.md - A persistent memory layer for your projects.

MindMux.ai — Wed, 24 Jun 2026 03:55:18 +0000

You spend an afternoon with a coding agent settling something real. Why Markdown over SQLite. Why option B is out. What "done" means for this version. The reasoning is good, the trade-offs are weighed, the call is made.

Then the session ends.

Open a fresh one tomorrow — or switch machines, or move from Claude Code to Codex — and the agent asks the same questions again. What does this project do? Why not B? Didn't we already decide this? The model isn't weak. It just never had anywhere durable to put the conclusion. The work survives as code; the why behind it evaporates into a chat log nobody reopens.

So we built a small standard for the missing piece, and we're open-sourcing it: brain.md.

What it is

brain.md gives a project a brain — its durable decisions, requirements, and constraints, written down as plain Markdown that lives in the repo and outlives every session.

Two things ship in the box:

A contract — a single BRAIN.md file at the project root that tells any coding agent how the brain works. An agent learns to use it just by reading that file.
A toolkit — a small brain CLI plus a few install-once skills that scaffold and maintain the brain.

The brain itself is just Markdown files in your repo — nothing to stand up before you start. It grew out of MindMux, our project-brain workbench, which drives a brain through MCP and a lot more. brain.md is the open layer underneath: the format and the contract, so any agent that can read a file can use one — with MindMux, or with nothing but your editor and a terminal.

What a brain actually looks like

It's a brain/ directory of Markdown, and it has two kinds of file.

Root pages — a fixed set of six, the project at a glance: background, architecture, flow, mindmap, stack, roadmap. These you only ever update.

Pages — one durable unit of knowledge each: a decision, a concept, a person, a reference. You create them as you go. There's no limit and no ceremony.

The part that makes a page more than a note is its shape. Every page carries two layers:

compiled_truth — the current best understanding, rewritable as a whole.
timeline — an append-only trail of how that understanding got there.

One layer keeps you moving. The other lets you trace your way back. When you overturn a past call, you don't quietly edit history — you append a reversal to the timeline, and the change of mind stays on the record.

The design bet: files plus a CLI

None of this is a new idea on its own. AGENTS.md and CLAUDE.md already let you hand an agent standing instructions. brain.md's bet is narrower and, I think, more useful: make the memory structured, and make it correct by construction.

Here's the mechanism. Reads and writes both go through the brain CLI — you never hand-edit a brain file. That sounds like a limitation; it's the whole point. Because the CLI is the only writer:

Frontmatter is always generated, so it can't drift into an invalid shape.
Rewriting compiled_truth and appending its timeline entry happen in one atomic write — so the understanding can never change without leaving a trace.

That second property is the one that matters. The most common way a knowledge base rots is a silent edit: someone changes the conclusion and the reasoning behind it is lost. Route every write through one command and that failure mode is structurally impossible. There's no validator in brain.md because there's nothing left for a validator to catch.

What's actually different

If you've reached for adjacent tools, here's the honest contrast.

vs. a flat CLAUDE.md / rules file — those are great for instructions, but they're one growing blob you maintain by hand. A brain is structured, addressable knowledge with a built-in audit trail. Different job.
vs. memory that lives inside a tool — a vector store, a model's own memory, a hosted service: those are runtimes over your knowledge. A brain is the substrate itself — plain files in git, diffable in a PR, readable by a human, an agent, or grep. Put a runtime on top of it (MindMux does, over MCP; more can) and the knowledge still belongs to the repo, not the tool.
vs. saving chat history — chat history is the process. A brain is the conclusion. You don't want every raw sentence back; you want the handful of judgments you'll need again.

It's also not locked to one model or one tool. The contract is a file, so the same brain works across Claude Code, Codex, and whatever you use next.

See it work

Install the tools once:

./setup        # links the skills into every agent you choose (~/.claude, ~/.codex, …)

Then, in any project, the agent scaffolds and seeds a brain (brain-setup, then brain-bootstrap), and from there it just works. The payoff shows up across sessions:

You    Let's store config as Markdown, not SQLite — easier to diff and migrate.

Agent  Capturing that as a decision so it outlives this session.
       $ brain create-page --id config-as-markdown --category decision \
             --title "Store config as Markdown, not SQLite"
       ✓ page created · indexed

— three weeks and a fresh session later —

You    Why aren't we using a database for config?

Agent  $ brain read-page config-as-markdown
       We chose Markdown for diff-ability and zero migrations. Here's the original
       call and the trade-offs we weighed …

No re-explaining. The next conversation starts from what you already settled.

Try it

A brain is memory for the project, not for the model. Plug in a different agent next month and the thing that stays is the brain.

If that's a problem you have, it takes about five minutes to feel:

Repo: github.com/mindmuxai/brain.md
Standard: projectbrain.md
Works with Claude Code and Codex today. Apache-2.0. Issues and PRs welcome.

If the first thing you notice is "I didn't have to explain all of this again," it's working. That's why we built it.

Originally published on MindMux Blog.

AI can write code now. It still forgets what you decided last week.

MindMux.ai — Wed, 24 Jun 2026 03:48:34 +0000

Opening a new chat and re-explaining the same background over and over is exhausting.

Not because the models are weak. Mostly because most AI tools store conversation history, not the parts of a project that are already clear.

You spend two hours discussing an architecture choice. The next day you open a fresh session, switch machines, or move from Claude to Codex, and the AI asks the same questions again: What does this project do? Why not option B? Did we already decide this?

That was the starting point for MindMux.

We were not trying to build another chat shell. We cared about something else: how to turn ongoing discussion into a project brain that does not lose its memory.

That brain/ is local. It is Markdown. It travels with the project. You can keep it in git, read it from different models, and continue on a different machine. The next conversation does not start from a pile of old messages. It starts from the background, decisions, constraints, and direction you already settled.

This post is not meant to sound grand. It is just about one thing: how we now use MindMux to move a project forward.

The workflow is basically three steps

Step 1: Discuss first. Do not rush into building.

At the start of a new project, the easiest mistake is not moving too slowly. It is starting too fast.

I usually spend a few rounds in MindMux on the same topic first. Sometimes it is product direction. Sometimes a technical plan. Sometimes the roadmap. Sometimes I just need to make a vague idea concrete.

The point is not to get an answer as fast as possible. The point is to make a few things stable:

What problem are we actually solving?
What are we definitely not doing?
What options do we have, and why are we choosing this one?
What is enough for this version?

You can think of it as building a small set of durable judgments before execution starts.

In MindMux, those conversations do not stay trapped in the chat window. Once a discussion settles, it gets distilled into brain/: sometimes as a project document, sometimes as a decision page, sometimes as background or constraints, sometimes as context that a later task must carry with it.

That difference matters:

Chat history is the process. Brain is the conclusion.

We do not want to save every raw sentence. We want to save the parts we will need again.

Step 2: Start building, but turn repeated actions into reusable skills

Once the direction is clear enough, then we start building.

At that point I do not want to keep typing a fresh natural-language request for everything: summarize the requirement, organize the background, prepare handoff context, collect the bug boundaries, and so on. If something happens often, it should become a stable workflow.

That is why slash commands in MindMux are not just a nice input trick. They are really entry points into skills.

Today the built-in set includes commands like /background, /ingest, and /handoff. They help with things like:

filling in project background quickly
distilling a conversation into brain
packaging context for a downstream agent

And from there, it is easy to imagine more project-shaped commands, for example:

/feat: turn a new idea into an executable feature brief
/fix: pull together the context, scope, and acceptance criteria for a bug
/review: surface the old decisions that matter before reviewing changes
/commit: look back at what this round of work actually changed

The important part is that these commands are not magic. In MindMux, they are created through the product's skill creation workflow. When you notice that a certain pattern keeps repeating, you can turn it into a reusable skill and it becomes a slash command you can call again later.

That matters because it turns repeated work into a shared protocol. You do not have to rephrase the same intent every time, and the AI does not have to keep guessing what you meant.

When a discussion has narrowed down to a concrete piece of work, MindMux can hand it off. It does not pretend to do every part itself. Instead it passes along the relevant brainRefs, background, constraints, and acceptance criteria to downstream executors like Claude Code or Codex.

That matters more than it sounds. A lot of projects do not fail because the work is impossible. They fail because the team forgets why something should be built a certain way right when execution begins.

Step 3: After each round, converge back into brain

This is the part I like most.

A lot of tools help you get started. Very few care about what happens after a round of work finishes.

Real development is not linear. You finish a feature and get user feedback. You fix a bug and realize an earlier assumption should change. You push the roadmap forward and discover that one direction should probably be cut.

If all of that ends up living only inside another chat transcript, it will still be gone a week later.

So my habit is simple: after each meaningful round, I use the skills we created to go back into brain and record what actually changed.

Not as a diary. As an update to the things that matter:

what the goal is now
which design is decided
which direction was rejected
which constraint matters more than before
where the next discussion should resume

That is also why a MindMux page is not just a loose note. It has a compiled_truth layer for the current best understanding, and a timeline layer for how that understanding formed.

One helps you keep moving. The other helps you trace your way back.

Why we care so much about brain

Because what really slows projects down is often not coding speed. It is context loss.

Without a brain, the same problems keep showing up:

every new session starts with another round of background explanation
switching models wipes out constraints that were already discussed
a week later you cannot remember why a choice was made
handing work to another agent means rewriting the setup all over again

Each one looks small by itself. Together they quietly drain a lot of attention.

Once you have a brain/, the whole feeling changes.

You are not maintaining a longer chat log. You are maintaining a long-term memory layer for the project itself.

A few properties matter a lot here:

it is not memory locked inside one model
it is not a black-box database
it is not tied to one session
it can move with the project across machines

The most immediate result is simple:

the direction stops drifting so easily.

That is especially valuable early on. You will discuss a lot, change details a lot, and test a lot of paths. But the big things that are already clear should not get broken apart every time a new conversation starts.

To me, MindMux is a discussion layer that does not forget

I think of it less and less as an AI client, and more as a long-term memory layer for the project.

You can plug in different models, but the thing that stays stable is the brain.

You can discuss product ideas, shape a plan, prepare tasks, revisit old judgments, and hand mature context to a downstream executor. The important part is that you are not starting from zero every time. Not in a new session. Not on another machine. Not after switching models.

That is what we wanted the first version to be.

Not a giant feature pile.

Just something that helps you repeat yourself less, lose fewer decisions, and spend less time rebuilding context you already earned.

If you want to try MindMux for the first time

Keep it simple:

Pick a real project, not a fake demo.
Use MindMux for one actual product or technical discussion that is currently stuck.
Once the discussion settles, write the background, key decisions, and constraints into brain.
The next time you open a new conversation, do not restate everything. Just continue.
When one piece of work is clear enough, hand it to a downstream model to execute.

If the first thing you notice is, "I did not have to explain all of this again," then it is already working.

That is why we are building it.

Originally published on MindMux Blog.