Claude Memory Skill

1# claude-memory-skill
2 
3```
4╔══●══●══●══════════════════════════════════════════════╗
5║                                                       ║
6║  > tree ~/.claude/memory                              ║
7║                                                       ║
8║    ├── core.md          claude-memory-skill           ║
9║    ├── topics/          ───────────────────           ║
10║    │   └── *.md         a skill is all you need       ║
11║    └── me.md                                          ║
12║                                                       ║
13╚═══════════════════════════════════════════════════════╝
14```
15 
16> *An embarrassingly simple and minimal implementation for agentic memory.*
17>
18> No databases. No embeddings. No semantic search. Just markdown files and a skill that teaches Claude when to read and write.
19 
20## The Problem
21 
22Claude Code forgets everything between sessions. Built-in auto-memory exists but:
23- It's opaque (Claude decides what's "meaningful")
24- Limited to 200 lines loaded at startup
25- Not tightly integrated into the agentic loop
26- No hierarchical organization (scales poorly)
27 
28## The Solution
29 
30A skill-based memory protocol with:
31- **Hierarchical storage**: `core.md` summaries → `topics/<topic>.md` details
32- **Background agents**: Memory ops don't block the main agent
33- **Categorized entries**: No dumping ground, everything has a topic
34- **Filesystem-based**: Robust, inspectable, git-trackable
35 
36## Installation
37 
38```bash
39curl -fsSL https://raw.githubusercontent.com/hanfang/claude-memory-skill/main/install.sh | bash
40```
41 
42Or clone and run locally:
43 
44```bash
45git clone https://github.com/hanfang/claude-memory-skill.git
46cd claude-memory-skill
47./install.sh
48```
49 
50## What Gets Installed
51 
52```
53~/.claude/
54├── CLAUDE.md              # Hook added (or created)
55├── commands/
56│   └── mem.md             # The memory skill
57└── memory/
58    ├── core.md            # Summaries + pointers (always loaded)
59    ├── me.md              # About you (always loaded)
60    ├── topics/            # Detailed entries by topic
61    │   └── <topic>.md
62    └── projects/          # Project-specific memories
63        └── <project>.md
64```
65 
66## Architecture
67 
68```
69┌─────────────────────────────────────────────────────┐
70│  Main Agent                                         │
71│  - Focuses on user's task                           │
72│  - Spawns memory agent when needed                  │
73│  - Doesn't wait (background)                        │
74└─────────────────────┬───────────────────────────────┘
75                      │ spawn (background)
76                      ▼
77┌─────────────────────────────────────────────────────┐
78│  Memory Agent                                       │
79│  - Reads core.md + relevant topics                  │
80│  - Writes to topic files                            │
81│  - Updates core.md summaries                        │
82└─────────────────────────────────────────────────────┘
83```
84 
85## How It Works
86 
87### Agent-Initiated (Automatic)
88 
89These run automatically — you don't invoke them:
90 
91| Action | When | Blocking |
92|--------|------|----------|
93| `load` | Session start | No |
94| `save` | Claude learns something useful | No |
95| `recall` | Claude needs context | No |
96 
97### User-Initiated (Manual)
98 
99These are for you to inspect and manage memory:
100 
101| Command | Description |
102|---------|-------------|
103| `/mem show` | Display memory structure and contents |
104| `/mem forget <topic>` | Remove a topic or specific entries |
105 
106### Tell Claude What to Remember
107 
108Just say it naturally:
109- "Remember that we use pnpm, not npm"
110- "Save that the API requires auth headers"
111- "Note that tests need Redis running"
112 
113### Fill In Your Profile
114 
115Edit `~/.claude/memory/me.md` with facts about yourself:
116 
117```markdown
118# About the User
119 
120- AI researcher, focus on agents and RL
121- Prefer explicit code over clever abstractions
122- Python, PyTorch, JAX
123```
124 
125### Hierarchical Memory
126 
127**core.md** (always loaded):
128```markdown
129# Core Memory
130 
131## Debugging
132Mostly async/timing issues. Prefer explicit logging.
133→ topics/debugging.md
134 
135## RL Research
136PPO tuning, reward shaping experiments.
137→ topics/rl.md
138```
139 
140**topics/debugging.md** (loaded on demand):
141```markdown
142## Async race condition fix [2024-01-15]
143Added explicit locks around shared state access.
144 
145## Redis timeout debugging [2024-01-10]
146Default timeout was too short for large payloads.
147```
148 
149### Write Flow
150 
1511. Learn something → spawn background memory agent
1522. Agent categorizes → finds or creates topic file
1533. Agent appends entry with timestamp
1544. If significant, agent updates core.md summary
155 
156### Read Flow
157 
1581. Session start → agent reads core.md + me.md in background
1592. When stuck → agent follows pointers to relevant topics
1603. Returns context to main agent
161 
162## Design Principles
163 
164- **Background ops**: Memory doesn't block the main agent
165- **Hierarchical**: Summaries in core.md, details in topics
166- **Categorized**: Every entry belongs to a topic
167- **Atomic entries**: One `##` block = one memory
168- **No semantic search**: Deterministic, grep-based retrieval
169- **User editable**: Plain markdown, edit anytime
170 
171## Uninstall
172 
173```bash
174rm -rf ~/.claude/memory
175rm ~/.claude/commands/mem.md
176# Manually remove the memory hook from ~/.claude/CLAUDE.md
177```
178 
179## License
180 
181MIT
182