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).

---

Where this comes from. Every post here comes from one setup I run daily: a CLAUDE.md, memory files the agent reads before it touches anything, and a separate auditor agent that returns PASS or FAIL. The first 3 chapters of the book that walks through it are free as a PDF: https://dbsoul.gumroad.com/l/autonomous-ai-agents-claude-code-free-sample

The full edition is 11 chapters plus 4 ready-to-use templates (CLAUDE.md starter, memory files, auditor checklist, measurement guide) and a hands-on section for every chapter, $19 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.

Comments

[Sungsoo Youn]

읽어 주셔서 고맙습니다. 말씀하신 분리(사람이 쓴 기록 / 자동으로 쌓이는 로그)가 실제로 핵심이었습니다. 섞여 있던 동안에는 이미 끝난 문제를 현재 이슈로 오인해 같은 자리를 16번 되짚었습니다. 지금은 자동 로그를 audit-log.md로 보내고, 주입 단계에서 한 번 더 거릅니다.

HANDOFF도 같은 이유로 '다음 세션이 모르면 사고 나는 것'만 남깁니다 — 분량이 늘면 다음 세션이 읽지 않고, 읽지 않는 기록은 없는 기록입니다.

[오피셜메일]

기록을 늘리는 것보다 누가 썼고 자동 주입되는지를 분리한 설계가 더 중요하다는 사례가 좋았습니다. 특히 자동 검사 로그가 mistakes.md에 섞여 이미 해결된 문제를 16번 반복했다는 경험은 audit-log.md 비주입 원칙을 납득시키네요. HANDOFF에는 다음 세션이 모르면 사고 나는 상태만 둔다는 기준도 기억의 양을 제어하는 데 실용적입니다.