Hindsight: Giving Claude Code a Memory of Its Mistakes

Human hindsight comes with a flaw: knowing the outcome changes how we remember the uncertainty that came before it. Decisions that once felt uncertain begin to look inevitable. Psychologists call this hindsight bias. It helps explain why post-mortems can slip so easily into blame. We judge past decisions using information we learned later, then call the judgment a lesson. Memory smooths over the confusion and gives us a cleaner, more convincing version of events.

The window closes quickly. Details fade within days. A few months later, the experience has become simpler and less accurate. In a year, you’ll be confidently explaining how it all went exactly according to plan.

Enough of the jibber-jabber, give me the skill!

GenAI Has an Extreme Version of the Problem

Working with coding agents all day exposed a severe version of the same problem.

Every session produces knowledge. The agent makes decisions and explains its reasoning. It encounters a trap, finds a workaround, abandons a dead end, or spends ten minutes searching for a document buried in an obscure directory. Then the context window closes. The next session begins without any memory of the previous one, making it likely to repeat the same mistakes.

The transcript still exists on disk, capturing the full sequence of events before any summarization or simplification. It shows the wrong assumptions, failed commands, abandoned approaches, and eventual fixes in order. Nobody re-reads their own transcript. Who has time for that?

So I Built a Skill That Does

hindsight reads an agent’s previous session transcripts and extracts the details worth carrying forward. It collects decisions and their reasoning, traps, slow paths, unfinished work, useful references, and fixes that should survive beyond one context window. The complete history goes into a dated report. The strongest lessons also get prepended toMEMORY.md which loads into the agent’s next session. Each new session begins with knowledge earned during the previous ones.

How It Works

One design boundary shaped the system: The model handles judgment. A small Python script handles the deterministic work. Durable lessons require context and evaluation. The model decides whether a failed command exposed a reusable constraint or merely documented a typo.

File discovery, repository resolution, timestamps, entry counts, and byte limits follow exact rules. hindsight.py handles those jobs in fewer than two hundred lines. The skill instructions guide the reading and interpretation. The scan uses a watermark. A state.json file stores the last_scan timestamp. Each run asks find for transcripts modified after that point.

The first run scans three days of history. The limit keeps the initial run focused and prevents it from processing the project’s entire transcript history. The watermark advances through a separate commit-scan step at the end of the run. If the process fails halfway through, the watermark stays where it was. The next run processes those sessions again, preventing a partial failure from silently skipping them.

Claude Code stores transcripts in directories based on modified project paths, where slashes and dots become dashes. The script rebuilds the correct directory name from the repository root and includes linked worktrees. The main repository and its worktrees share one memory to avoid splitting the project’s history. The script resolves the main repository with: git rev-parse --git-common-dir so that a run from the primary checkout behaves the same as a run from a linked worktree.

Keeping Memory Useful

MEMORY.md loads into every session, so it has to stay small. I cap it at roughly six kilobytes, or about fifteen hundred tokens. New lessons go at the top of a fenced section marked by two HTML comments. When the file crosses the limit, the pruning step moves the oldest entries into MEMORY.archive.md. Manually curated notes below the fenced section stay in place.

Before adding an entry, the script checks its title against both the current memory file and the archive, ignoring dates. This prevents the same lesson from appearing twice. It also treats archived lessons as known history, so they are not added back into active memory. Dated reports remain append-only beside the memory files. MEMORY.md carries the lessons worth loading into every session. The reports preserve the full history.

Failed Commands Produce the Best Evidence

A command fails, gets retried with another flag, hits a missing dependency, or stalls on authentication. Each failure yields a command, exit code, and attempted fixes. Non-zero exit codes reveal friction and wasted effort. hindsight records the failing command, exit code, and working fix, and may suggest checking dependencies, reusing the successful invocation, validating paths, or skipping steps when authentication is unavailable.

The next session can use the working command immediately.

What It Can Change

The system has a narrow scope. It writes a report and updates memory. Its authority ends there. It can flag a skill that needs improvement, propose a new skill, or identify a script worth extracting. Each recommendation includes the source of friction, where it occurred, and a plausible fix.

hindsight leaves implementation for a deliberate follow-up. It cannot edit another skill, create tickets, or modify the surrounding system during an unattended run.

A person still decides which recommendations deserve action.

Testing the Part Nobody Watches

The script includes a selfcheck. It creates a temporary memory file, adds entries, prunes it, and verifies the result. The newest entries survive. The oldest move into the archive. Curated pointers must remain in place. Title normalization must prevent duplicates. These failures would be easy to miss during an unattended run. A corrupted memory file could sit unnoticed for weeks while making future sessions less useful. The tests focus on the parts most likely dto fail without producing an obvious warning.

What Hindsight Changes

Agents need a discipline humans often neglect: write down what you learned while the details are still sharp. Capture the failed command, wrong assumption, and unexpected constraint before the experience becomes a cleaner story. Preserve the surprise while it can still improve the next decision. A system can perform that work consistently.

Hindsight cannot repair the previous session. Its value appears in the next one.