How to Give Claude Long-Term Memory With File-Based Context

Claude doesn't remember anything between sessions. That's fine for one-off questions, but an agent that works with the same customer for months needs to keep track of decisions, people and constraints.

A folder of plain files that Claude can read and write is the most dependable way to do that.

Why plain files work well

You can open them, compare versions, keep them in git and delete anything wrong. If the agent acts on something incorrect, you can find the file it came from and fix it. That's much harder with an embedding store you can't easily inspect.

Step 1: Choose where memory lives

• Claude Code loads CLAUDE.md files automatically. Use them for project conventions, commands and architecture notes.
• Agents built on the API can use Anthropic's memory tool (memory_20250818). Claude asks to view, create and edit files in a memory directory, and your code carries out those file operations, so you control where the files are stored.

Step 2: Lay out the folder

memories/
  INDEX.md            # one line per memory, read every session
  customer-acme.md    # stakeholders, systems, constraints
  decisions.md        # what was decided, when, and why
  preferences.md      # how this team likes to work

The index is the most important file. Claude reads it at the start and opens other files only when they're relevant, which keeps the context small.

Step 3: Say what should be saved

In the system prompt, list what's worth remembering:

• Decisions and the reasons for them.
• Facts about people, systems and constraints that aren't written down elsewhere.
• Corrections from users, such as "don't mock the database in tests".

Also list what shouldn't be saved: secrets, information already in the repository and passing conversation.

Step 4: Keep the memory accurate

• Write dates as real dates, not "last Tuesday".
• Update an existing file rather than creating a near-copy.
• Delete memories that turn out to be wrong.
• Read through the folder now and then, the way you'd review configuration.

Things to watch

• Every file Claude reads uses input tokens. Keep files short and specific.
• Treat memory as information, not instructions, especially if users can influence what gets saved.
• Keep a separate memory folder for each customer so details never cross between them.

Start with an index and three topic files. Once you see what the agent actually saves, you can adjust the structure.