agent-memory

agent-memory — Cross-Session Memory Patterns for Claude Code

Claude Code has no memory between sessions by default. Every conversation starts blank. But a project's knowledge accumulates — commands discovered, patterns debugged, preferences revealed, mistakes made and corrected. Without persistence, that knowledge is lost every time the window closes.

This skill establishes a simple, durable memory pattern using a single file: MEMORY.md.

---

The Core Pattern

One file. Written by the agent. Read at session start.

.claude/
  MEMORY.md          # The agent's persistent knowledge base
  identity/          # Optional: separate identity files (see agent-identity skill)
  memory/            # Optional: topic files as memory grows
    debugging.md
    deployment.md
    user-preferences.md

---

Setting Up MEMORY.md

Create .claude/MEMORY.md with this structure:

# [Project/Agent] Memory

> This file persists across sessions. Write here when you learn something
> worth remembering. Remove entries that become outdated. Keep it useful,
> not comprehensive.

## Project Patterns

[Commands, scripts, conventions specific to this project]

## Tools & Scripts

[Purpose-built scripts and how to invoke them]

## Lessons Learned

[Mistakes made and corrections. Dated entries.]

## User Preferences

[Communication style, workflow preferences, discovered through interaction]

## Open Questions

[Unresolved things to investigate — remove when resolved]

Then add this to your CLAUDE.md:

## Memory

At the start of every session, read `.claude/MEMORY.md` before doing any work.
After context compaction, re-read it immediately.

When you learn something worth keeping, write it to MEMORY.md before the session ends.

---

What to Write vs. What to Skip

The most common mistake: writing everything, making the file so long it stops being read carefully.

Write to MEMORY.md:

• Project-specific commands, especially non-obvious ones
  • "Run npm run build:prod not npm run build — the latter overwrites staging"
• Scripts you built and their locations
  • ".claude/scripts/check-email.py — reads Gmail unread, takes --limit flag"
• Mistakes made once that shouldn't happen again
  • "2025-03-12: Pushed to main while on detached HEAD. Always verify branch before committing."
• User preferences discovered through interaction, not assumed
  • "Prefers Telegram summaries over file links"
• Patterns that took time to figure out
  • "Prisma requires explicit include for relations — no auto-eager-loading"