4. Memory Management — Cleanup, Rotation, Prioritization

Description

MEMORY.md is a plain text file your subagent reads at startup and updates during execution. It sounds simple — and it is, mechanically. But the detail that turns useful memory into counterproductive memory is a number: 200 lines. Claude Code automatically injects the first 200 lines of MEMORY.md into the subagent's system prompt. Anything after line 200 exists in the file but isn't loaded automatically — the agent would have to read it explicitly, which it won't do unless you instruct it to.

This means MEMORY.md isn't a log where you accumulate everything. It's a curated resource where the most important content must be in the first 200 lines. An uncurated MEMORY.md grows with each session: first it has 50 useful lines, then 150, then 300 — and at that point the 200 auto-injected lines include stale information about decisions that already changed, patterns that were already refactored, and conventions the team abandoned two sprints ago. The agent acts on incorrect information because you don't have a curation system.

In this capsule you'll learn to manage the complete lifecycle of a subagent's memory: what to keep at the top, what to archive, what to delete, and how to instruct the agent itself to participate in its curation. An agent with well-curated memory is more effective than one with infinite memory — because the signal isn't lost in the noise.

The 200-Line Problem

How automatic injection works

When a subagent with memory: project is invoked, Claude Code does this before executing any instruction:

1. Looks for .claude/agent-memory/{name}/MEMORY.md
2. Reads the first 200 lines
3. Injects them at the start of the subagent's context
4. Runs the subagent's system prompt with that context

What it doesn't do:

❌ Doesn't read past line 200
❌ Doesn't prioritize content within those 200 lines
❌ Doesn't detect whether the content is stale
❌ Doesn't automatically archive old content

Uncontrolled growth

Without curation, a typical MEMORY.md evolves like this:

Week 1 (30 lines):
- Naming conventions: snake_case
- Framework: FastAPI with SQLAlchemy
- Tests: pytest with shared fixtures

Week 4 (120 lines):
- Everything above +
- 15 discovered patterns
- 8 architectural decisions
- 5 recurring issues with solutions

Week 8 (350 lines):                       ← PROBLEM
- The first 200 lines include:
  - Conventions (still valid)
  - Week 1 decisions (some already changed)
  - Week 2 patterns (some refactored)
- Lines 201-350 include:
  - More relevant recent decisions       ← NOT INJECTED
  - Current project patterns             ← NOT INJECTED

Result: the agent makes decisions based on context from 2 months ago, ignoring the most recent decisions that are past line 200.

The fundamental rule

What's after line 200 doesn't exist for the agent — unless it reads it explicitly.

Your job as curator is to ensure the 200 auto-injected lines contain the most relevant and current information. Everything else must be archived or deleted.

Anatomy of a Well-Curated MEMORY.md

Recommended categories

A MEMORY.md structured by categories is easier to curate than a chronological one. These are the 4 categories that cover 90% of cases:

# Agent Memory: code-reviewer

## Architecture Decisions
- API follows REST conventions with /api/v1/ prefix
- Repository pattern: all DB access goes through src/repositories/
- DTOs separate from domain models — never expose ORM models in responses
- Background tasks use Celery, not FastAPI BackgroundTasks

## Coding Conventions
- Python: snake_case functions, PascalCase classes, UPPER_CASE constants
- Imports: stdlib → third-party → local (isort enforced)
- Type hints required on all public function signatures
- Docstrings: Google style, required on public functions
- Error responses: always use ProblemDetail (RFC 7807)

## Known Patterns
- Auth: JWT with refresh tokens, stored in httponly cookies
- Pagination: cursor-based on all list endpoints (no offset)
- Validation: Pydantic v2 models in src/schemas/
- Logging: structured JSON via structlog, correlation IDs on all requests

## Recurring Issues
- N+1 queries in product listings — use selectinload()
- Missing error handling on external API calls (payment gateway)
- Test fixtures create too much data — use factory_boy minimal fixtures

Why categories and not chronology

A chronological format ("Session 2026-03-01: I learned that..., Session 2026-03-05: I discovered that...") has two problems:

1. Duplication: The same convention appears in multiple session entries
2. Temporal priority: The oldest entries are at the top, the newest at the bottom — exactly the opposite of what you want

The category format groups related information and lets you update an entry without duplicating it. If the naming convention changes from snake_case to camelCase, you update one line in "Coding Conventions" instead of having two contradictory entries in different sessions.

Priority ordering: the most important at the top

Within the file, order the categories from highest to lowest impact:

1. Architecture Decisions     ← maximum impact, changes rarely
2. Coding Conventions         ← high impact, stable
3. Known Patterns             ← medium impact, evolves
4. Recurring Issues           ← variable, changes frequently

Within each category, the most important item goes first. If the 200-line limit cuts off in "Recurring Issues," you lose the least frequent issues — acceptable. If it cut off in "Architecture Decisions," you'd lose fundamental decisions — unacceptable.

Curation Strategies

What to keep

Keep in MEMORY.md information that meets these three criteria:

1. Current — Reflects the project's current state (not reverted decisions)
2. Actionable — The agent can use this information to make better decisions
3. Non-obvious — The information can't be inferred by reading CLAUDE.md or the code

✅ KEEP: "Pagination is cursor-based, never use offset — performance degrades on tables > 1M rows"
   → Current, actionable (the agent knows which pattern to use), non-obvious (the why of cursor)

❌ DELETE: "The project uses Python"
   → Obvious — the agent discovers it by reading pyproject.toml

❌ DELETE: "In session 2026-02-15, we decided to use FastAPI"
   → The project already uses FastAPI — it's a fact, not a pending decision

What to archive

Archive information that's no longer immediately actionable but could be useful as a historical reference:

Archive:
- Reverted decisions (to understand why X was tried and didn't work)
- Patterns from previous framework versions
- Resolved issues that could recur in large refactors

The archive goes to a separate file in the memory directory:

.claude/agent-memory/code-reviewer/
├── MEMORY.md          ← active, first 200 lines auto-injected
└── ARCHIVE.md         ← historical reference, not auto-injected

What to delete

Delete without archiving:

- Debugging notes from a specific session ("tried X, didn't work, then tried Y")
- Information redundant with CLAUDE.md
- Information the agent trivially rediscovers (tech stack, directory structure)
- Temporary annotations ("TODO: review this tomorrow")

Self-Curation Instructions in the System Prompt

The problem of manual curation

Curating MEMORY.md manually works for one agent. For three or five agents with daily runs, it becomes significant overhead. The solution is to instruct the subagent to curate its own memory.

Curation instructions in the system prompt

Add a Memory Management section at the end of your subagent's system prompt:

---
name: code-reviewer
description: Reviews code changes with persistent memory of project patterns
tools: Read, Glob, Grep, Bash
disallowedTools: Write, Edit
model: haiku
maxTurns: 15
memory: project
---

## Role
[... your existing system prompt ...]

## Memory Management

At the END of each session, update your MEMORY.md following these rules:

### What to update
- Add new patterns discovered in this session
- Add new architectural decisions observed
- Update entries that are no longer accurate
- Remove entries about issues that have been fixed

### Organization rules
- Use EXACTLY these categories: Architecture Decisions, Coding Conventions, Known Patterns, Recurring Issues
- Keep the most important items at the TOP of each category
- Each entry must be a single line starting with "- "
- No timestamps, no session references, no narrative text

### Size constraint
- MEMORY.md must stay under 180 lines (buffer for the 200-line limit)
- If approaching 180 lines, remove the least relevant entries from Recurring Issues first
- NEVER exceed 200 lines total

### What NOT to store
- Information already in CLAUDE.md (don't duplicate)
- Temporary debugging notes
- Information obvious from reading the code
- Session-specific observations that won't matter next time

Verify that curation works

After several sessions, verify the size:

wc -l .claude/agent-memory/code-reviewer/MEMORY.md

If it exceeds 180 lines, reinforce with "CRITICAL: Never exceed 180 lines" in the system prompt or run a manual curation as a checkpoint.

If you want the agent to archive instead of delete, add: "When removing an entry, append it to ARCHIVE.md in the same directory with the date."

Memory Rotation

When to rotate

Rotation is the process of moving content from MEMORY.md to reference files. Rotate when:

• MEMORY.md is approaching 180 lines and all the content is relevant
• One category dominates the file (e.g., 80 lines of Recurring Issues)
• The project passes a milestone and the context changes significantly

Rotation structure

.claude/agent-memory/code-reviewer/
├── MEMORY.md              ← active (≤ 180 lines)
├── ARCHIVE.md             ← removed entries with date
├── patterns-v1.md         ← patterns from Phase 1 of the project
└── decisions-log.md       ← history of architectural decisions

Rotation instructions in the system prompt

### Rotation rules
- If a category exceeds 30 entries, move the oldest 15 to ARCHIVE.md
- When a major refactoring happens, move affected patterns to
  a versioned file (patterns-v1.md, patterns-v2.md)
- Architecture Decisions are NEVER rotated — they stay in MEMORY.md
  unless explicitly reverted

Rotated files aren't injected automatically. The agent can access them if you instruct it in the system prompt: "If you encounter a familiar issue not in MEMORY.md, check ARCHIVE.md."

Detecting Stale Memory

Signs of stale memory

Memory becomes counterproductive when:

1. Reverted decisions — MEMORY.md says "we use offset pagination" but the project migrated to cursor-based
2. Deprecated patterns — The agent recommends a pattern that no longer applies because the framework was updated
3. Resolved issues — "N+1 in product listings" is recorded as a Recurring Issue but the fix is already in production
4. Abandoned conventions — "Google-style docstrings" when the team switched to NumPy-style

Automatic detection via system prompt

### Stale detection
Before applying any memory entry, verify it's still accurate:
- If MEMORY.md says a convention exists, check 2-3 files to confirm
- If MEMORY.md says an issue is recurring, check if it's been fixed
- If you find a stale entry, update or remove it immediately
- Add a note in your session output: "Updated stale memory: [what changed]"

Periodic audit

Every 2-4 weeks, review MEMORY.md asking yourself about each entry: is it still true? does the agent act on this? would anything change if I remove it? If the 3 answers are "no," delete the entry.

For an automated audit, ask Claude Code:

Read .claude/agent-memory/code-reviewer/MEMORY.md and the current code
in src/. Identify entries that are no longer accurate because the code
changed. List each stale entry with what it says vs what the code
currently shows.

Aggressive vs Permissive Curation

Two philosophies

Aggressive curation prioritizes precision over completeness. Permissive curation prioritizes completeness over brevity. Both have real tradeoffs.

Aggressive curation

## Memory Management (aggressive)

Keep MEMORY.md under 100 lines. Only store:
- Active architectural decisions (max 10)
- Current coding conventions (max 10)
- Top 5 most impactful patterns
- Top 3 most frequent issues

Remove everything else. When in doubt, remove.

Permissive curation

## Memory Management (permissive)

Keep MEMORY.md under 190 lines. Store:
- All architectural decisions with context
- All coding conventions observed
- All patterns discovered
- Issues seen more than once

Only remove entries confirmed as incorrect.

When to use each one

The default recommendation

For most projects, start with aggressive curation (100 lines) and relax if you feel the agent loses context it needs. It's easier to add than to remove — a 190-line MEMORY.md full of noise requires a complete audit, but an 80-line one only needs you to add what's missing.

Manual vs Automated: Curation Approaches

Hybrid curation: the recommendation

Combine the agent's self-curation with human oversight:

Automated:      every session (the agent does it on its own)
Quick manual:   every 1-2 weeks (5 min, verify the auto-curation works)
Full audit:     every 4-6 weeks (15 min per agent)
After refactor: immediately (forced manual curation)

Example: Week 1 vs Week 8

Without curation (week 8, 210+ lines)

## Architecture Decisions
- REST API with /api/v1/ prefix
- [Session 2026-02-01] Decided to use offset pagination     ← STALE
- [Session 2026-02-22] Switched to cursor pagination         ← contradicts the previous one
- ...50 more entries, timestamps, session narratives...

Contradictory content, stale entries, unnecessary timestamps. The recent decisions are past line 200 — the agent doesn't see them.

With curation (week 8, 28 lines)

## Architecture Decisions
- REST API with /api/v1/ prefix
- Repository pattern for all DB access
- Redis caching on read-heavy endpoints (products, categories)
- SQLAlchemy 2.0 async for all DB operations
- Cursor-based pagination on all list endpoints

## Coding Conventions
- snake_case for functions, PascalCase for classes
- Pydantic v2 models in src/schemas/ (never expose ORM models)
- Structured logging with structlog, correlation IDs required

## Known Patterns
- JWT auth: access token (15min) + refresh token (7d), httponly cookies
- Validation: request/response models separate (CreateProduct vs ProductResponse)

## Recurring Issues
- Payment gateway timeouts: wrap in retry with exponential backoff
- Test fixtures too heavy: use factory_boy with minimal data

Concise, up to date, without contradictions. Each entry is actionable.

Troubleshooting

"MEMORY.md grows out of control"

Cause: The curation instructions in the system prompt are too permissive or don't exist.

Solution: Add an explicit limit and a prioritization rule:

CRITICAL: MEMORY.md must NEVER exceed 180 lines.
If it approaches 180 lines, remove entries in this order:
1. Recurring Issues that haven't appeared in 3+ sessions
2. Known Patterns available in CLAUDE.md
3. Coding Conventions obvious from reading the code
NEVER remove Architecture Decisions unless they've been reverted.

"The agent ignores its own memory"

Cause: MEMORY.md has too many lines and the relevant information is past line 200, or the content is so generic it doesn't produce different decisions.

Solution: Verify the size and quality:

wc -l .claude/agent-memory/code-reviewer/MEMORY.md
head -200 .claude/agent-memory/code-reviewer/MEMORY.md

If it has more than 200 lines, curate. If the content is generic ("use good naming"), replace it with specific information ("functions use verb_noun pattern: get_user, create_order").

"The agent deletes memory it should keep"

Cause: The curation instructions are too aggressive, or the agent doesn't distinguish between fundamental and secondary information.

Solution: Mark critical entries as permanent:

## Architecture Decisions [PERMANENT — never remove without explicit instruction]
- Repository pattern for all DB access
- Cursor-based pagination on all list endpoints

The [PERMANENT] tag instructs the agent not to touch those entries during automatic curation.

"Two subagents have contradictory memory"

Cause: Each agent discovered the same information in different sessions and recorded it differently.

Solution: Designate one agent as the "source of truth" for each category: reviewer for Patterns and Issues, implementer for Conventions and Architecture. Each agent reads the other's memory as a reference but only writes to its own categories.

"I don't know which scope to use"

Quick rule:

Exercises

Exercise 1: Curate a bloated MEMORY.md (Easy)

This MEMORY.md has 25 entries but the project only needs 12 lines. Identify what to delete, what to keep, and why.

# Agent Memory: code-reviewer

## Architecture Decisions
- The project uses Python 3.12
- REST API with FastAPI
- Repository pattern for DB access
- We considered Django but chose FastAPI
- SQLAlchemy 2.0 for ORM
- Database is PostgreSQL
- [2026-01-15] Set up the project structure
- Background tasks with Celery

## Coding Conventions
- snake_case for functions
- Use type hints
- PascalCase for classes
- Imports should be organized
- We use Black for formatting

## Known Patterns
- JWT authentication
- Pydantic for validation

## Recurring Issues
- Sometimes tests are slow
- Need to add more tests
- The CI pipeline takes 10 minutes
- Found a bug in the payment module last week
- Memory usage is high on production

# Agent Memory: code-reviewer

## Architecture Decisions
- Repository pattern: all DB access through src/repositories/
- Background tasks: Celery for jobs > 30s, FastAPI BackgroundTasks for < 30s
- SQLAlchemy 2.0 async with connection pooling

## Coding Conventions
- snake_case functions, PascalCase classes, UPPER_CASE constants
- Type hints required on all public function signatures

## Known Patterns
- JWT auth with refresh tokens, access token TTL 15min
- Pydantic v2 models in src/schemas/ for all request/response validation

## Recurring Issues
- Tests slow when using real DB — use fixtures with factory_boy
- CI pipeline: 10min — parallelize test suites to reduce
- Memory usage in production: paginate all list endpoints, limit query results

Exercise 2: Write self-curation instructions (Easy)

Given this tester subagent, write the Memory Management section for its system prompt. The tester has local scope and its memory should focus on test performance and failure patterns.

---
name: code-tester
description: Runs tests and reports results
tools: Bash, Read, Glob
disallowedTools: Write, Edit
model: haiku
maxTurns: 12
memory: local
---

## Memory Management

At the END of each session, update your MEMORY.md:

### Categories (use exactly these)
- **Test Performance:** Slow tests (> 2s), test suite total time trends
- **Failure Patterns:** Tests that fail repeatedly, common root causes
- **Coverage Trends:** Module coverage percentages, uncovered areas
- **Environment Notes:** Machine-specific config, virtualenv paths, known setup issues

### Rules
- Keep under 120 lines (aggressive — test data changes frequently)
- Only record patterns seen in 2+ sessions
- Remove entries about tests that have been deleted
- Remove entries about failures that have been permanently fixed
- Track test suite execution time trend: add current time each session,
  keep only last 5 measurements

### What NOT to store
- Individual test results (only patterns)
- Full error messages (only root cause summary)
- Temporary workarounds that lasted one session

Exercise 3: Design a rotation strategy (Medium)

Your reviewer has been on a project for 3 months. MEMORY.md has 175 lines, all relevant. The project is about to start Phase 2 with a significant refactor. Design a rotation strategy: what do you move, where to, what do you keep?

cp .claude/agent-memory/code-reviewer/MEMORY.md \
   .claude/agent-memory/code-reviewer/phase-1-memory.md

### Phase awareness
- Phase 1 patterns archived in phase-1-memory.md
- If an issue seems related to Phase 1 code, check phase-1-memory.md
- Patterns discovered in Phase 2 take priority over Phase 1 entries
- Remove Phase 1 references from MEMORY.md if the code was refactored

Exercise 4: Detect and fix stale memory (Medium)

Analyze this MEMORY.md and the current state of the code. Identify the stale entries and write the corrected MEMORY.md.

Current MEMORY.md:

## Architecture Decisions
- Offset pagination on all endpoints
- SQLAlchemy 1.4 with sync sessions
- Monolithic architecture, single service

## Coding Conventions
- No type hints (team decided against them)
- print() for debugging, no logging library

## Known Patterns
- Auth: session-based with Flask-Login
- Validation: manual if/else checks in route handlers

Current state of the code (pyproject.toml):

[project]
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.110",
    "sqlalchemy>=2.0",
    "pydantic>=2.0",
    "structlog>=24.0",
    "python-jose[cryptography]>=3.3",
]

## Architecture Decisions
- Cursor-based pagination (verify current implementation)
- SQLAlchemy 2.0 async sessions
- FastAPI application (migrated from Flask)

## Coding Conventions
- Type hints: required (Pydantic v2 enforces them on models)
- Structured logging via structlog (no print statements)

## Known Patterns
- Auth: JWT tokens via python-jose (migrated from session-based)
- Validation: Pydantic v2 models (migrated from manual checks)

## Recurring Issues
- [needs discovery] — previous issues likely resolved during migration

Exercise 5: Memory budget for a team of 3 subagents (Hard)

You have 3 subagents with project scope (reviewer, implementer, tester). Define a "memory budget" — how many maximum lines for each agent and each category, justifying the allocations. Available budget: 180 lines per agent.

Summary

• MEMORY.md has a practical limit of 200 lines — only the first 200 are automatically injected into the subagent's context
• Organize the memory into 4 categories: Architecture Decisions, Coding Conventions, Known Patterns, Recurring Issues
• Keep the most important content at the top — Architecture Decisions first, Recurring Issues at the end
• Curation = keep, archive, or delete — each entry must be current, actionable, and non-obvious
• Instruct the subagent to self-curate at the end of each session with explicit rules in the system prompt
• Rotation: move content to secondary files (ARCHIVE.md, phase-X.md) when MEMORY.md fills up but the information is valuable
• Detect stale memory by verifying entries against the current code — reverted decisions and deprecated patterns confuse the agent
• Aggressive curation (~100 lines) for active projects, permissive (~180 lines) for stable projects
• The hybrid approach (self-curation + periodic manual review) is the most robust for most teams
• Well-curated memory is a prerequisite for Module 3 — parallel agents need shared memory without noise to coordinate

Additional Resources

1. Subagents — Persistent Memory (Anthropic Docs) — Official documentation of the memory field, scopes, and MEMORY.md
2. Create Custom Subagents — Complete YAML frontmatter reference including memory
3. Claude Code Best Practices — Context-management best practices that apply to memory curation
4. Prompt Engineering: Be Clear and Direct — Clarity techniques for self-curation instructions in system prompts
5. CLAUDE.md Documentation — How CLAUDE.md complements (doesn't duplicate) agent memory
6. Claude Code Tips and Tricks — Tips on context management and memory
7. Prompt Caching (Anthropic) — How context caching works and why smaller memories are more efficient
8. Claude Models — Context on context windows and how memory size impacts performance

Next capsule: In capsule 05 you'll build a complete memory hierarchy for the 3 subagents from Module 1. You'll configure project scope for the reviewer and implementer, local for the tester, add curation instructions to each system prompt, and verify that memory persists across sessions. It's the culminating project of the module — if your 3 agents remember and curate their context, you've mastered memory management.