Give Your AI a Memory

A fresh AI session forgets everything. The single highest-leverage move in this entire system was solving that — with four plain text files and a 30-second startup routine that turns a goldfish into a genuine colleague.

The Goldfish Problem

In Part 1 we named the core constraint: an AI session has no continuity. Every time you start a new conversation, the model arrives with zero context about your project — the decisions you made last week, the mistakes you already paid for, the work currently in flight. You end up re-explaining the same foundations over and over, and the AI confidently re-litigates the same questions you already settled.

The fix is not to somehow extend one session forever. The fix is to build an external memory the AI reloads at the start of every session. Once that's in place, a reset is just a breath — work continues without interruption because the context is always current, always there, always readable in under a minute.

This is the single change that made everything else in the system possible.

The Four Types of Memory

Not all information ages the same way. Some things are true right now and will change soon. Some things were decided once and should never be re-decided. Some things are lessons that must be kept permanently so the mistake never repeats. And some things are the baton for the next shift. These four categories need four separate files — mixing them is how they all become stale and useless.

Type 1 — State (what is true right now)

This is the live snapshot: which sites are active, how many pages each one has, what infrastructure is running, what is currently broken, what was recently deployed. It changes constantly, so it gets updated constantly — after every meaningful deploy or status change. Think of it as a dashboard rendered as markdown.

The key discipline: keep it current and keep it terse. A state file that hasn't been updated in a week is worse than no state file — it's a lie the AI will act on confidently.

Type 2 — Decisions (settled choices, stop re-litigating them)

Every project accumulates architectural choices: the color scheme, the ad loading strategy, the canonical URL format, which technology handles which job. Once a decision is made and working, it goes in this file with a one-line rationale. The AI reads it at startup and stops proposing alternatives to things that are already settled.

This file is the end of the recurring "should we reconsider..." conversations that eat session time. The answer is in the file: it was decided, here is why, do not reopen it.

Type 3 — Lessons (mistakes already paid for)

This is the most valuable file in the system and the easiest to neglect. When something goes wrong — a deploy that silently rolled back weeks of work, a rate limit that stalled an entire batch job, a monitor that went quietly dark for days without alerting anyone — you write a lessons entry immediately, while the failure is fresh. You write it for the next AI session that will have no memory of the incident.

Write lessons in second person, imperative: "Never deploy from a working copy before checking it is in sync with the shared source. Always verify through the real public surface, not a synthetic ping." Future-you, reading this in a fresh session, needs no context — just the rule.

Type 4 — Handoff (the session-to-session baton)

The handoff file is updated at the end of every session and read at the start of the next. It answers three questions: what was just completed, what is currently in flight, and what is the top priority for the next session. It is the baton in a relay race. We cover this in depth in Part 3, but it belongs in this overview because it is part of the same memory system.

The File Structure

Here is the exact structure we use. Plain markdown, plain files, one folder. No database, no special software — just files that both humans and AI can read and write:

memory/
  STATE.md       # live snapshot — update after every deploy or status change
  DECISIONS.md   # settled choices with one-line rationale — rarely changes
  LESSONS.md     # mistakes and the rules that prevent them — grows over time
  HANDOFF.md     # session baton — rewritten at session end, read at session start

You can put these anywhere in your project. The only requirement is that the AI's startup instructions tell it to read all four before doing anything else.

The Startup Routine (30 Seconds)

The memory system only works if the AI actually uses it. The startup routine is a single instruction at the top of your system prompt or at the start of every session:

Before doing anything else:
1. Read STATE.md — what is true right now
2. Read DECISIONS.md — what has already been decided
3. Read LESSONS.md — what mistakes must not repeat
4. Read HANDOFF.md — what was in flight and what comes next

Only after reading all four: confirm you have loaded context, then begin work.

That is it. Thirty seconds of reads, and the AI arrives with full context. In practice, a well-written set of four files can be read in well under a minute, and the payoff is immediate: no re-explaining the project, no re-litigating settled decisions, no repeating avoidable mistakes.

How to Keep These Files Useful

Four files that are not maintained are four files that mislead you. Here is the maintenance protocol that keeps the system honest:

• STATE.md — update it immediately after anything meaningful changes. Deployed a new set of pages? Update the count. Turned off a feature? Note it. The rule is: do not close a session without updating STATE if anything changed.
• DECISIONS.md — add to it whenever a non-obvious choice is made. One line: what was decided, one line: why. If you find yourself re-discussing a decision, that is a signal it belongs in this file and does not yet live there.
• LESSONS.md — write entries immediately after incidents, while the failure is fresh. Never defer. The lesson you write six days later is vague; the lesson you write six minutes later is actionable. Keep entries in present-tense, imperative rules.
• HANDOFF.md — the last thing you do in every session, the first thing the next session reads. We cover the format in detail in Part 3, but the minimum is: completed, in-flight, next priority.

What Changes When This Is Working

The shift is immediately noticeable. Before external memory, every session started with ten minutes of context-setting. Decisions made the previous week were questioned again. Lessons from incidents were nowhere in the conversation. The operator spent more time orienting the AI than directing it.

After, the AI arrives oriented. It knows which sites are live and which are being built. It knows the chosen ad strategy and does not propose alternatives. It knows that deploying from a stale working copy is a hard rule violation, because the lesson is right there in the file. The first message of a session can be a work directive, not a recap.

Start Small, Then Expand

You do not need all four files on day one. Here is the order of operations:

1. Start with STATE.md — just describe what your project is and what currently exists. Even a five-line file is better than nothing.
2. Add LESSONS.md after your first incident — write down what happened and the rule it produced. This file earns its value the moment it prevents a recurrence.
3. Add DECISIONS.md after you notice yourself re-explaining the same choice twice. The second re-explanation is the signal that it belongs in the file.
4. Add HANDOFF.md when your sessions start producing meaningful continuity — when you have real in-flight work that needs to carry over. Part 3 covers this in detail.

Four files, built incrementally, maintained honestly. This is the foundation every other part of the system rests on. Without it, orchestrators and worker agents and quality gates are all building on sand — context evaporates between sessions and you are back to re-explaining everything from scratch.

Your action for this part: create a memory/ folder in your project right now. Open STATE.md and write five lines: what the project is, what currently exists, and what is actively in progress. That first file, even imperfect, is the beginning of a system that compounds.