1.1 Why LLMs Need Memory Systems
LLMs (Large Language Models) start every session from scratch, with no concept of "what we discussed yesterday." This leads to three engineering challenges:
- Redundant Effort: You have to re-explain project context, command preferences, and architectural decisions every time.
- Lost Experience: Previously resolved bugs, tuned configurations, and lessons learned disappear.
- Cross-Project Barriers: Experiences gained in Project A cannot be easily transferred to Project B.
The essence of a memory system is: Turning "out-of-session" knowledge into context that the LLM can access "in-session." Claude Code addresses this through three complementary mechanisms.
flowchart LR
A[Out-of-session Knowledge] --> B{Memory Mechanisms}
B --> C[CLAUDE.md
Manually written rules]
B --> D[auto memory
LLM-written notes]
B --> E[claude-mem
Auto-captured logs]
C --> F[LLM Context]
D --> F
E --> F1.2 Overview of the Three Mechanisms
| Feature | CLAUDE.md | auto memory | claude-mem |
|---|---|---|---|
| Source | Official Anthropic | Official Anthropic | Third-party (thedotmack) |
| Writer | User (Manual) | LLM (Autonomous) | Hooks (Auto-captured) |
| Content Type | Coding standards, architecture | Preferences, project decisions | Tool calls, bug fixes, decisions |
| Storage | Plain Markdown | Plain Markdown | SQLite + Chroma (Vector DB) |
| Loading | Full load at startup | Load index (first 200 lines) | Injection + MCP retrieval |
| Scope | Project / User / Org | Single working tree | Cross-project Global |
Simple Analogy:
- CLAUDE.md = The Project Constitution (rules you establish).
- auto memory = The LLM's Notebook (learning your preferences and project specifics).
- claude-mem = A searchable database of work logs (retaining traces of all past tasks).