claude-recap

Topic-based automatic memory for Claude Code — never lose context across sessions or compactions.
English | 中文
---
The Problem
Claude Code forgets everything between sessions. Switch topics mid-conversation and the previous context is gone. Hit a context compaction and your working state evaporates. Start a new session and you're explaining the same project from scratch.
What Claude-Recap Does
Two shell hooks that run automatically — zero manual effort:
- **Automatic topic archival** — Every response gets a topic tag. When the topic changes, the previous one is summarized and saved to a Markdown file.
- **Context injection** — Each new session starts with your topic history and remembered preferences injected automatically.
- **Compaction recovery** — When Claude Code compacts your context, Claude-Recap cold-reads from the JSONL transcript to rebuild accurate summaries. Nothing is lost.
- **/remember skill** — Tell Claude to remember preferences across sessions: "always use bun", "never auto-commit". Stored in plain Markdown.
Everything is stored locally as Markdown files in ~/.memory/. No database, no cloud, no dependencies beyond bash and Node.js.
Quick Start
Plugin install (recommended)
> **Note:** After install, restart Claude Code for hooks to take effect. /remember works immediately, but topic features (/save-topic, /list-topics, auto-archival) require the restart to inject the Topic Tag Rule.
Manual install (without plugin system)
This writes hook entries directly into your project's .claude/settings.json.
How It Works
Features
| Feature | How |
|---------|-----|
| Topic-based archival | Stop hook detects topic changes, archives with summaries |
| Cross-session memory | SessionStart hook injects previous topics + preferences |
| Compaction recovery | Cold-reads JSONL transcripts when context is truncated |
| /remember | Persist preferences globally or per-project |
| /save-topic | Manually checkpoint current topic progress |
| /list-topics | View all topics discussed in current session |
| Delayed archival | Background process archives topics from past sessions |
| 100% local | Plain Markdown in ~/.memory/, no cloud, no database |
Storage
All data lives in ~/.memory/ (configurable via MEMORY_HOME env var):
Comparison
| | Claude-Recap | claude-mem | Manual CLAUDE.md |
|---|---|---|---|
| Granularity | Per-topic | Per-session dump | Manual |
| Automation | Fully automatic | Automatic | Manual |
| Compaction survival | Yes (cold-read recovery) | No | N/A |
| Storage | Local Markdown | ChromaDB | Local Markdown |
| Dependencies | bash, Node.js | Python, ChromaDB | None |