Brain, Explained

Alright, let’s talk about AI coding. If you’ve been using ChatGPT, Codex, Claude… whatever your weapon of choice is — you’ve probably felt this already. Sometimes it’s insane. Like… how did it just write that? Other times, it’s just frustrating. You explain something. It kind of gets it. Then you ask something else and it completely forgets everything you just said.

I’ve hit that wall a lot.

What’s actually going wrong

It’s not that AI is bad, it’s that AI doesn’t know your project. It doesn’t know:

how your code is structured
why things are the way they are
what you’ve already tried
what just changed

So every time you ask it to do something, it’s basically guessing. And yeah… sometimes it guesses right, but a lot of times it doesn’t.

This is where Brain comes in

Brain is super simple. It just lives inside your project and does one job:

it keeps track of what matters, and feeds the right context into AI

That’s it! No crazy UI, no “platform”, no extra thing you have to manage.

Quick example

Let’s say you’re fixing a bug:

token refresh race condition

Normally you’d:

open a few files
copy some code
explain the problem
paste it into AI

And hope for the best. Now with Brain:

brain context compile --task "fix token refresh race condition"

That one command pulls together:

past bugs you’ve written down
the files involved
nearby tests
your project structure
what’s currently changing

Now AI actually understands what it’s working on. That’s a huge difference!

The three things Brain is doing

You don’t really need to understand everything, but this helps.

1. Memory

Your project stops forgetting stuff. Fix a bug? Save it. Make a decision? Save it. Now it’s part of the project forever and AI can use it later.

2. Retrieval

You can actually find things.

brain search "auth bug"

Instead of digging through files or trying to remember where something was.

3. Context

This is the big one. Instead of throwing your whole project at AI… Brain builds a small, focused packet for whatever you’re working on. Only what matters, no noise.

Real world difference

Let’s say you’re adding a new endpoint.

Without Brain:

AI makes up structure
naming is off
auth is wrong
logging doesn’t match

You end up rewriting half of it. With Brain:

it sees your existing endpoints
it follows your patterns
it fits into your system

Now you’re just reviewing instead of rewriting.

Sessions (lightweight, but useful)

When you start working:

brain session start --task "add endpoint"

Brain keeps track of what’s going on, so when you finish:

brain session finish

It just checks:

did you verify things?
did you save anything important?

Nothing crazy. Just enough to keep things clean.

Distill (this part is actually really nice)

After a session:

brain distill --session

It’ll suggest:

what changed
what might be worth saving

You review it, keep what matters, and move on. That’s it.

The part I didn’t expect

After using this for a bit… Your project starts to feel different. It remembers things, it adapts and gets more consistent, and you stop doing this loop of:

explain → fix → explain again → fix again

Why I don’t build without it anymore