What is a contextbase? The asset that makes agents remember

Open a fresh session with any AI coding agent and check what it knows about your project: nothing. Not the decision you made last week about how authentication works. Not the bug that took three hours to corner on Tuesday. Not the reason you chose one database over the obvious alternative. The model is brilliant, and it's starting from zero — again.

That blank slate is the biggest hidden tax on building with agents. You pay it every session, in re-explaining what you already explained. The fix isn't a smarter model. It's a contextbase — and once you have one, your agent stops starting from zero.

The problem: a brilliant agent with no memory

An AI coding agent has no memory between sessions. Close the laptop, and everything it understood about your project is gone. The chat history feels like memory, but it isn't — it scrolls away, it hits the context window limit (the finite amount the model can hold at once), and nobody else on the project can read it. Anthropic's own engineers describe the core challenge of long-running agents as exactly this: keeping what matters when the working memory fills and the session ends.

So you compensate. You re-paste the same context at the top of every session. You re-explain the architecture. You watch the agent confidently re-introduce a bug you already fixed, because it has no idea the fix ever happened. The work isn't compounding — it's evaporating, and you're the backup drive.

What a contextbase is

A contextbase is the folder of plain markdown that your agent reads before it acts. It lives in git, right next to your code, and you version it the same way.

Here's the whole idea in one line: every software project actually runs two systems.

• The codebase — what runs. The code that ships.
• The contextbase — what guides. The briefs, decisions, patterns and gotchas that say how and why the code got built.

Traditional development optimises only the first. You commit code carefully and let the reasoning behind it live in your head, in Slack, in a chat log that's gone by Friday. With an AI agent on the team, that's a fatal gap — because the agent can't read your head. It can only read what's written down.

Stuart Leo

A codebase is what runs. A contextbase is what guides. You've been keeping one of them in git and the other in your memory.

The contextbase closes the gap. It makes the knowledge a first-class artifact — written, committed, and read by the agent on its way in.

What goes inside

A contextbase isn't elaborate. Four kinds of file carry most of the weight:

docs/
├── AGENTS.md          ← the Router: the one file the agent reads first
├── 02-working/        ← briefs (what to build) + session notes (what happened)
└── 03-knowledge/      ← gotchas and decisions (what you learned, why you chose)

• The Router — one file (named AGENTS.md or CLAUDE.md on disk) that the agent reads first. It's an index, not an encyclopedia: it points to everything else so the agent can find what a task needs.
• Briefs — short specs of what to build and, just as important, what not to build.
• Session briefs — a few lines at the end of a session: what changed, why, what's verified, what's next. This is the written memory the next session reads.
• Gotchas and decisions — the trap you hit recorded once, and the reason behind a choice so nobody re-litigates it cold.

That's it. Markdown a business builder can write and a senior developer can trust.

Why it compounds

Here's the part that changes how building feels. Chat history evaporates. A contextbase accrues.

Every session, you write down what was learned and commit it. So the next session — and the next agent, and the next person — start from everything figured out so far, not from zero. The gotcha you captured on Tuesday saves Thursday's session an hour. After fifty sessions, the contextbase is denser in real decisions than the code itself.

And the two systems multiply each other. A richer contextbase makes the agent's code more precise and less likely to repeat old mistakes. Cleaner code surfaces patterns worth capturing back into the contextbase. Context improves code, code improves context — a loop that gets sharper the longer you run it, instead of an explanation you give again and again.

There's an honest cost: it asks for a little discipline every session. You write the brief. You capture what was learned. That's the price of compounding, and it's a real ask — but it's minutes, and it's the only thing here that turns effort into an asset you keep.

Start your first one

You can have a contextbase by the end of today:

1. Make a docs/ folder in your repo.
2. Add one Router file (AGENTS.md) that says, in plain words, what this project is and where things live.
3. At the end of your next session, write five lines: what changed, why, what's verified, what's next. Commit it.

That's a contextbase. Tomorrow your agent reads it before it acts — and for the first time, it starts ahead.

Your agent stops forgetting the moment its context lives in git instead of the chat window. That's the whole shift: stop being the memory, and start building one.

Start here: read the C² method, run your first session, or learn the discipline underneath it in context engineering, explained.