Issue #1029
Claude Code ships with two built-in memory systems. CLAUDE.md lets you write persistent instructions. Auto memory lets Claude write its own notes across sessions. Understanding both — and then knowing when to add claude-mem on top — is the key to a context-aware workflow.
Built-in memory: CLAUDE.md
CLAUDE.md is a plain markdown file that loads into every session. Write things you want Claude to always know: build commands, code style rules, architecture decisions, workflow preferences.
# Generate a starting file from your codebase
/init
Claude analyzes your project and creates a CLAUDE.md with what it finds. Edit from there.
Auto memory
Auto memory is Claude writing notes to itself. When you correct Claude, establish a preference, or it discovers something worth remembering, it saves a note without you asking.
Notes land in ~/.claude/projects/<project>/memory/:
memory/
├── MEMORY.md # Index, loaded into every session
├── debugging.md # Detailed debugging patterns
└── api-conventions.md # API decisions
The first 200 lines of MEMORY.md load at the start of every conversation. Topic files are read on demand. Claude keeps the index concise by moving details into separate files.
When you want Claude to remember something specific, just ask: “remember to always use pnpm, not npm.” It writes that to auto memory. To put something in CLAUDE.md instead, ask directly: “add this to CLAUDE.md.”
Memory files are plain markdown. You can read, edit, or delete them anytime. Run /memory to browse and open them from within a session.
claude-mem: cross-session observation capture
The built-in systems store instructions and preferences. claude-mem adds a different layer: it captures what happened across sessions — tool calls, decisions made, bugs fixed, patterns discovered — and makes them searchable.
Install it:
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
This registers lifecycle hooks and starts a background worker on port 37777.
The worker watches every session and compresses observations into a SQLite database with full-text search, backed by a Chroma vector database for semantic queries. A session where you debugged a race condition becomes a 200-token summary, not a 4,000-token transcript.
Search past observations
The primary way to query is the mem-search skill:
/mem-search how did we fix the auth bug
This runs a two-step search. First, a fast query returns compact results with IDs:
search(query="auth bug fix", type="bugfix", limit=10)
Then fetch full details only for what you need:
get_observations([42, 67])
Fetching everything at once wastes tokens. The two-step pattern costs a fraction of the context.
You can also open claude-mem dashboard at http://localhost:37777/
Start the conversation