Give your AI a memory that survives restarts

The problem

Every new AI session starts empty. The agent that knew your stack, your preferences, and every decision you made yesterday wakes up today knowing nothing, so you re-explain everything and lose half the session before real work starts. Chat memory dies with the session. Files do not.

How I give my agents a memory

The fix is boring, which is why it works: the memory lives on disk as plain markdown, not in the chat. My Claude Code memory folder holds close to forty small files, one markdown file per fact: one per project, one per preference, one per lesson learned. Each file opens with a couple of frontmatter lines (a name and a one-line description) and then the detail.

Next to them sits MEMORY.md, the index: one line per file with a link and a short summary. The index loads at the start of every session; the detail files get read only when a task needs them. Every session begins already knowing what exists and where to look. It is the between-sessions half of the same idea as saving your context before it runs out: the model writes notes for its future self.

The rule that keeps the folder from rotting: update in place, never duplicate. When a project moves forward, the agent edits that project’s file and its index line. A new file only appears for a genuinely new topic.

Copy the structure

1. Create a memory folder in your project:

memory/
  MEMORY.md        # the index, one line per file
  project-site.md  # one topic per file
  preferences.md

2. Paste these rules into your CLAUDE.md or system prompt:

Memory rules:
- At the start of every session, read memory/MEMORY.md. It is the
  index of everything you know about me and my projects.
- One topic per file inside memory/. Check the index before writing:
  if the topic already has a file, update that file. Never create a
  second file for the same topic.
- When a fact changes, edit the old fact. Do not append a
  contradiction below it. Date important updates.
- After any change, update that file's one-line entry in MEMORY.md.
- Keep MEMORY.md short. Detail lives in the topic files.

3. Seed it. Tell your agent three things worth remembering, let it write them, then restart and ask what it knows about you.

An agent that writes what it learns to disk never starts from zero again.

Do this now

1. Create memory/MEMORY.md in the project you use most.
2. Paste the rules block into that project’s CLAUDE.md.
3. Quiz a fresh session on the three facts you seeded.

When the folder outgrows what one index can hold, the next step is to ask your notes anything with a local RAG.