Give the agent memory
An agent forgets everything between sessions unless the memory lives in files it is told to load. This is the setup that survives a restart, a crash and a new laptop.
Why files, not a longer prompt
A system prompt is a fixed cost paid on every message. Memory is a lookup: a small index at the start of a session, then a handful of files read only when the task needs them.
That difference is what keeps a long-running setup affordable. The agent does not carry every lesson in context. It carries a list of where the lessons are.
Where it lives
Claude Code reads a memory directory configured in ~/.claude/settings.json. Keep it outside the vault and link it in, so git can version it without the vault.
{
"autoMemoryDirectory": "/Users/you/Control-Panel/claude-config/config/auto-memory"
}Use an absolute path
The tilde is not expanded inside this setting. Write the full path, or the agent will create an empty directory wherever it happens to start.
What is in it
├── MEMORY.md the index, loaded every session
├── user-name.md who the person is
├── no-em-dashes.md a writing rule and the reason behind it
├── goal.md the one goal everything ladders up to
├── projects/
│ └── stackmcp.md a project convention with a scope
└── mistakes/
└── local-first-restructuring.mdMEMORY.md is not the memory. It is a table of contents: one line per file, with a short hook so the agent can decide whether to open it.
One file, one fact
Every memory is a single markdown file with frontmatter. Four types cover almost everything: who the person is, how they want work done, what is in progress, and where to find something external.
---
name: no-em-dashes
description: Never use em dashes in anything written for him; they read as an AI tell.
metadata:
type: feedback
---
Never use em dashes in copy, notes, commits or UI text.
**Why:** it is the clearest tell that a model wrote the sentence.
**How to apply:** use a period, a comma or a colon instead.
Related: [[voiceover-script-style]]userrecords who the person is and how they work.feedbackrecords a correction or a confirmed approach, with the reason, so it can be applied to a new situation.projectrecords a goal or constraint that the code does not state.referencepoints at a URL, ticket or dashboard.
Short links between files ([[name]]) are what turn a folder of facts into something the agent can follow when one memory raises a question another one answers.
Keeping it honest
- Update the existing file instead of writing a second one that says the same thing.
- Delete a memory that turned out to be wrong. Two active memories that contradict each other are worse than none.
- Do not store what the repository already records: file layout, past fixes and git history are facts the agent can read.
- Give every project convention a scope, and never generalize it to another project.
The test
If a new session would do the work correctly without the file, it does not belong in memory.