Article 4 of 12 · ARTHA Craft
I was treating the chat like a filing cabinet. It was a whiteboard designed to be erased.
There is a moment every developer using AI agents eventually hits.
You close the chat. You open a new one. You start typing, and somewhere in the first five minutes you realise you are rebuilding context from scratch. Again. Explaining the architecture. Again. Re-stating the constraint. Again.
It feels like a workflow problem. A tooling problem. Something a better model or smarter interface should fix.
It isn't any of those things. It is a storage problem. And the solution has been sitting in front of you since the first day you learned to write code.
Every conversation I had ever had with an AI agent lived in one place: the chat window. And the chat window has a lifespan. It opens. It fills. It closes. And everything inside it, every decision, every constraint, every "we agreed on this approach because of these three reasons", disappears with it.
🗒 What the chat actually is
A whiteboard. Brilliant for thinking. For working something out in real time. For collaboration in the moment. Nobody stores architecture decisions on a whiteboard and walks away expecting them on Monday morning.
📁 What I was treating it as
A filing cabinet. A place where decisions lived. A record I could return to. Session after session, whiteboard after whiteboard, walking away expecting permanence from something designed to be temporary.
The moment I understood this, really understood it, the solution became obvious.
Stop using the chat as storage. Start using documents. [1]
⚡ The most common counter, and why it fails
I can already hear it. Most people try this. I did too. One long session. Never close it. Keep adding to it. Problem solved.
Here is what actually happens.
The context window fills and the model starts compressing. Every AI has a finite limit. As the session grows, older content doesn't sit quietly: the model summarises it, compresses it, eventually drops it entirely to make room for new input. The decision you locked in hour one? By hour five the agent is working from the model's compressed summary of it, not your original reasoning.
You haven't solved the memory problem. You've made it invisible. [2] When the model decides what to compress and what to keep, it is making architectural decisions on your behalf. Silently. Without telling you what got dropped or whether the nuance it discarded actually mattered.
One crash. Everything gone. Browser closes. Network drops. Laptop dies at the wrong moment. A structured document survives anything. An open tab survives nothing it wasn't designed to survive.
Your session is yours alone. Another developer cannot read your open chat. They cannot pick up from it in a new context or hand it to a different agent. The document can go anywhere. The tab goes nowhere.
At least when you write a handoff document, you control what survives. With compaction, the model controls it.
A document exists outside the conversation. It persists when the chat closes. It is there Monday morning. It is there when a new session opens. It is there when a different agent picks up the work. It is there when a new developer joins the team six months from now.
This is where most people stop halfway. They start writing things down: in a README, a Notion page, a sprawling wiki that grows until nobody can find anything in it. That is not the system. That is the old problem wearing a document's clothing.
The system requires documents with specific jobs. Each one covers a layer. Each one is maintained as part of the work, not as an afterthought, not "when there is time," but in the same session where the work happens.
The Constitution
What the platform is. What it cannot be. The non-negotiables governing every decision. Changes rarely and deliberately. The first thing any agent reads. The foundation everything else sits on.
The Current State
What has been built recently. What is partially done. What is in progress. Not a history, a snapshot. Keeps the constitution lean while capturing the living reality of where the product is right now.
The Roadmap
Every step ever planned or completed. Status visible at a glance. Nothing removed, history preserved. If it is not on this list, it has not been planned. If it is done, it is not revisited without an explicit decision.
The Session Bridge
Written at the end of every session. Read at the start of the next one. Where we stopped. What was decided. What is open. What is next. Makes every new session self-contained: no re-explaining, no blank slate.
The Task File
One document per feature. Background, design decisions, cross-layer dependencies, constraints, go-ahead prompt. The agent builds from this. Not from memory. Not from the chat. From a structured brief approved before a single line of code is written.
The objection I hear most often: "That sounds like documentation overhead. I don't want to slow down."
The honest answer from 25 years of building software:
The conversation ends.
Every time. Without exception. The window closes. The context dissolves. The compaction happens silently whether you planned for it or not.
The document survives.
Every time. Without exception. If you maintain it. That is the entire methodology in one sentence.
Everything else, the session structure, the task files, the handoff rituals, the registers, is the practical application of that one principle.