Issue 00 · Autumn 2026日本語 · RSS
AgentKoji

Designing Agent Memory

Claude Code memory: our MEMORY.md index and a session-start handover file that grew to 247KB. How we write indexes and spot rotting notes.

Letting an agent keep notes feels like it gets smarter. Months later the notes are bloated, stale, and sometimes wrong. Here is what went wrong with Claude Code memory and handover files for us, and how we design them now. Environment: Linux, Claude Code 2.1.301, Python 3.13.5, on 2026-10-16.

Claude Code memory and the MEMORY.md limit

Claude Code loads the auto-memory index MEMORY.md only up to the first 200 lines or 25KB at session start (https://code.claude.com/docs/en/memory, checked 2026-10-16). Our 200 Japanese index lines came to 13,199 bytes, so line count is the limit that matters. For CLAUDE.md length, see Trim Your CLAUDE.md.

Give every index line a trigger

Notes only work when read. We had a note saying “read before starting,” and the agent fell into the same hole without reading it. Each index line now says when to open it (“when a commit is rejected,” “must read before discussing a production restart”). Notes opened in the same situation are merged, with sources recorded in merged_from. Every note needs Why: and How to apply:, and memory writes go through an ask hook so a human approves them.

Policy in memory, state elsewhere

Memory holds lasting policy only. Current state lives in the handover file and git. State in notes rots: we debugged against an environment value from the handover file that had changed three days earlier. Re-read real values right before deciding. Re-check earlier diagnoses too: “committed but the row is missing” was wrong; a time zone made the job look as if it stopped three hours earlier.

Version corrected conclusions

Corrected notes get a version number and “read version 3 first.” Retired analysis scripts go to an archive with a retirement header, a line in the README table, and “do not cite these numbers” in the original results document.

Session-start files bloat

Our task file reached 90–120KB and the handover file 247KB. Once, 40 sessions of log lines piled onto the task file’s “last updated” line, making it 65KB. Now finished tasks shrink to one line, and work logs go to the handover file and commit bodies.

Notes frame the next decision

Notes an agent writes become the next agent’s frame. Asked to explore new approaches, the agent anchored on past results recorded in memory and drifted back to refining the old one. When you want fresh ideas, consider not loading those notes.

Suspect injected context

An agent once tried to use an LLM provider nobody asked for. The API config was fine; an external tool had written its activity log into CLAUDE.md. After removing the tool, 40 injected entries remained in other AI tools’ config directories and in ~/CLAUDE.md. Claude Code loads every CLAUDE.md from the working directory upward at launch (same source), so a file in your home directory reaches every project beneath it.

#!/usr/bin/env bash
# find-claude-md.sh: list CLAUDE.md files from cwd up to /
d=$(cd "${1:-.}" && pwd)
while :; do
  for f in "$d/CLAUDE.md" "$d/.claude/CLAUDE.md" "$d/CLAUDE.local.md"; do
    [ -f "$f" ] && echo "$f ($(wc -c <"$f") bytes)"
  done
  [ "$d" = / ] && break; d=$(dirname "$d")
done

With a test file in the home directory, it showed up alongside the project’s own file. /context inside a session also lists what loaded (same source).

Checking an agent’s reports against reality: don’t trust “done”.

Three layers and expiry dates

We use the “LLM Wiki” shape: raw sources, LLM-compiled pages, and a schema, with the LLM doing the upkeep that usually kills knowledge bases. Each page has status, confidence and review_due, and a lint catches problems:

a.md: expired 2026-09-30
c.md: missing ['confidence', 'review_due']

Keep generated output apart from human notes. Over 90% of our notes store had become machine output; “hard to find” was contamination, not folder structure. Isolation fixed it, not reorganizing. Where no official reference exists, grade each claim as official, community, disputed or refuted, and grow it by measurement.

Summary