# The AI Agent Memory Kit — 4 templates that turn a goldfish into a colleague

> Free, MIT-licensed, tool-agnostic. Works with any AI assistant that can read files at the
> start of a session (Claude, ChatGPT with a project, a local model, etc.).
> From the "How We Built It" series at grandewebnetwork.com.

A fresh AI session remembers nothing. The single highest-leverage fix is an **external,
structured memory** the AI reloads every time it starts. Four files. Plain markdown. That's it.

Copy these, fill the brackets, and tell your AI: *"At the start of every session, read these
four files before doing anything."*

---

## 1. STATE.md — what is true right now
Keep this CURRENT, not historical. Delete stale lines. This is the world as it exists today.

```markdown
# STATE — last updated [DATE]

## What this project is
[One paragraph: the goal, the audience, the current phase.]

## What's live / done
- [Thing] — [where it lives] — [status]

## In progress
- [Thing] — [who/what is on it] — [next step]

## Known issues / risks
- [Issue] — [severity] — [plan]

## Key facts the AI needs every time
- [URLs, names, conventions, "we always do X this way"]
```

---

## 2. DECISIONS.md — settled choices (stop re-litigating)
Every time you make a call you don't want to re-argue next week, log it here. The AI reads it
and stops re-opening closed questions.

```markdown
# DECISIONS — settled architecture & choices

## [Area, e.g. "Design"]
- [DATE] [The decision]. Reason: [why]. Do not re-discuss.

## [Area, e.g. "Tools"]
- [DATE] We use [X], not [Y], because [reason].
```

---

## 3. LESSONS.md — mistakes already paid for
The most valuable file. Each entry is a mistake you don't want to repeat, written so future-you
(and the AI) recognize and avoid it. Lead with the symptom so it's searchable.

```markdown
# LESSONS — hard-won, do not repeat

- **[Short title]** ([DATE]) — SYMPTOM: [what you saw]. CAUSE: [root cause].
  FIX: [what actually worked]. RULE: [the durable takeaway].
```

Example (a real one):
```markdown
- **Bulk AI content fabricates facts ~20%** — SYMPTOM: a strict review flagged ~1 in 5
  generated pages with an invented date/origin. CAUSE: confident-but-wrong is AI's default
  failure mode. FIX: a separate review pass that quotes any dubious claim; ship only what
  passes. RULE: never publish unverified factual content, especially when it feels low-stakes.
```

---

## 4. HANDOFF.md — the session-to-session baton
Update this at the END of every working session (or when context gets full). The NEXT session
reads it first and picks up cold, no re-explaining.

```markdown
# HANDOFF — for the next session

## What I did this session
- [Shipped / changed / decided]

## In flight (pick this up first)
- [Task] — [exact next step] — [where the files are]

## Blocked / waiting on
- [Thing] — [what unblocks it]

## Don't forget
- [Anything that would be lost if not written down]
```

---

## How to use them (the 30-second routine)
1. **Session start:** AI reads STATE → DECISIONS → LESSONS → HANDOFF.
2. **During:** when a decision is made, append to DECISIONS. When something breaks and you fix
   it, append to LESSONS.
3. **Session end:** AI updates STATE + writes HANDOFF.

Keep each file **terse and current**. A memory that's 50 pages of history is a memory nobody
reads. If STATE.md is getting long, you're storing history that belongs in git, not in memory.

*Next in the series: the session handoff in depth, and the quality gate that keeps AI from
shipping the fabrications LESSONS.md warns you about.*