Memory-Driven Development — Making the AI Remember What It Did Yesterday

This is chapter 3 of my book **Building Autonomous AI Agents with Claude Code* — a field guide to turning Claude Code from a coding assistant into an agent that remembers, verifies its own work, and knows when to stop. Everything below is from a system I actually run every day on one Windows PC.*

1. The AI's Fatal Weakness Is Not Skill — It's Memory

Give the same AI the same project, and if it doesn't know yesterday's trial and error, it trips
over the same spot again today. The solution isn't switching models — it's building
file-based external memory.

Let's clear up one misconception first. "Can't you just feed it a good summary?" — No.
A summary only works on the premise that you already know what matters. But yesterday's me
didn't know what would become a problem today. That's why records must be the original text,
not a summary — and instead, they must be split up so they're easy to find.

2. The 4-File Structure

File	What	When it's read
memory/diary.md	Chronological work context	Session start
memory/mistakes.md	Only mistakes a human pointed out	Session start
memory/MEMORY.md	A map of facts that don't change	Session start
memory/HANDOFF.md	Current state and what to do next	First of all

diary.md — the work journal. Accumulate a few lines per session: "when, what, why,
and how it ended." If you make date headers (## 2026-08-07 ...) a rule, it's easy for a hook
to extract and inject only the recent entries.

mistakes.md — the mistake record. Fixing the format is the key.

## [2026-08-06] Blamed the account for a 403 without checking my own file
- **- **What went wrong****: Saw a reasonless 403 and suspected their system three times
- **- **Why it was wrong****: Skipped what I control (file format) and looked at their side first
- **- **The right way****: Check my output, then my call, then the account. Before checking, say "candidate", not "cause"

A record that ends with "I did it wrong" cannot prevent repetition. Only when the third line
(the correct method) is there does the record become prevention. The AI in the next session can
change its behavior by reading that line alone.

MEMORY.md — the core index. A single page holding only the project's invariant facts
(structure, constraints, prohibitions). If diary is the chronological flow, MEMORY is the map.

HANDOFF.md — the handover note. Write only what will cause an accident if the next
session doesn't know it.

## What is running now
- Daily 09:30 collector (verify: schtasks /query /tn ...)
## Changes that must not be reverted
- Weakness scoring is OFF. Measured evidence says so; do not turn it back on because "the rule says so"
## Waiting on the owner's decision
- Ebook price, whether to enter the competition

This file was added last, but in practice it became the most frequently read file.

3. Rule: Enforce "Check Records Before Working" Structurally

Even if the records exist, they're useless if the AI doesn't read them. Enforce it in two layers.

1. State in the rule file: "before modifying code, open the records directly with the Read tool."
2. Use a hook (Chapter 4) to technically block "modifying files without having read the records."

Without ②, ① gets followed only intermittently. Especially as the session grows longer, rules
get pushed to the back of the context.

4. When Records Ruin Judgment (An Actual Incident)

This is the most important part of this chapter. Records are an asset, but once contaminated,
they become a liability.

The incident: logs produced by an automated inspection script were piling up in mistakes.md,
and the AI mistook those automated logs for current issues, repeating the same wrong answer
16 times. It kept seeing an already-resolved problem as "the problem right now."

The cause: mistakes.md is a file that gets auto-injected every session. If automated logs
get mixed in there, the AI's entire field of view is contaminated.

The fix: split the files by signal source.

File	Who writes it	Injected?
mistakes.md	Only what a human pointed out	✅
diary.md	Actual work by human and AI	✅
audit-log.md	Automated logs from scripts and cron	❌

And add one more filter to the injection hook.

def is_auto_noise(line):
    return any(m in line for m in AUTO_MARKERS)

Making the filter explicit strings rather than regex is deliberate. Cast the net too wide
and human-written entries get filtered out too — narrowing the field of view in the opposite
direction this time.

5. Another Form of Contamination — Encoding

Record files must be written only through a path that guarantees UTF-8 (the AI's file tools).
Writing via shell redirect (echo ... >> diary.md) can corrupt the encoding on Windows, and
if a corrupted record gets injected every session, you end up with an AI whose memory is damaged.

6. When Should Records Be Written?

If you define the "record this" instruction as a bundled procedure, no step gets skipped.

Step ③ kept getting skipped, so it eventually became a hook. If a commit succeeds but the
handover note wasn't updated today, a notification appears (Chapter 4, pattern C).

---

Want the whole system? The book has 10 chapters plus 4 ready-to-use templates (CLAUDE.md starter, memory files, auditor checklist, measurement guide) and a hands-on section for every chapter. It's $9.99 as a PDF: https://dbsoul.gumroad.com/l/autonomous-ai-agents-claude-code

Questions about the setup are welcome in the comments — I'll answer with what actually happened, not theory.