https://github.com/hatawong/claude-recap
Topic-based automatic memory for Claude Code — never lose context across sessions or compactions.
https://github.com/hatawong/claude-recap
agent-memory ai-memory anthropic bash claude claude-code claude-code-hooks claude-code-plugin context-management developer-tools llm-tools open-source productivity session-management shell
Last synced: 4 days ago
JSON representation
Topic-based automatic memory for Claude Code — never lose context across sessions or compactions.
- Host: GitHub
- URL: https://github.com/hatawong/claude-recap
- Owner: hatawong
- License: mit
- Created: 2026-03-03T20:44:26.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-06T08:20:45.000Z (3 months ago)
- Last Synced: 2026-04-20T01:03:39.411Z (about 1 month ago)
- Topics: agent-memory, ai-memory, anthropic, bash, claude, claude-code, claude-code-hooks, claude-code-plugin, context-management, developer-tools, llm-tools, open-source, productivity, session-management, shell
- Language: JavaScript
- Size: 1.81 MB
- Stars: 29
- Watchers: 1
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-claude-code-toolkit - claude-recap - topic session memory using Shell hooks — archives each conversation topic as a separate Markdown summary. Two hooks, bash + Node.js, 100% local | (Plugins / All Plugins)
README
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)
```bash
# 1. Register the marketplace
/plugin marketplace add hatawong/claude-recap
# 2. Install the plugin (choose User scope for all projects)
/plugin install claude-recap@claude-recap-marketplace
# 3. Restart Claude Code to activate hooks
```
> **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)
```bash
git clone https://github.com/hatawong/claude-recap.git
cd claude-recap
./scripts/dev-register.sh /path/to/your/project
```
This writes hook entries directly into your project's `.claude/settings.json`.
## How It Works
```
SessionStart hook Stop hook
│ │
▼ ▼
Inject into session: Compare topic tag
• REMEMBER.md (preferences) with .current_topic
• Topic history │
• Topic Tag Rule ┌────────┴────────┐
│ │ │
▼ Same topic Topic changed
Claude responds with → pass → exit 2
topic tag: › `slug` → LLM writes summary
│ → script archives to
▼ ~/.memory/
Every response tagged
automatically ┌─────────────────────────┐
│ Compaction recovery: │
│ .compacted detected → │
│ cold-read from JSONL → │
│ accurate summary saved │
└─────────────────────────┘
```
## 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):
```
~/.memory/
REMEMBER.md # Global preferences
projects/
{project-path-encoded}/ # e.g. -Users-you-my-app
REMEMBER.md # Project preferences
{session-id}/
.current_topic # Active topic slug
01-setup-auth.md # Topic summary (auto-numbered)
02-fix-login-bug.md
```
## 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 |
| Topic separation | Automatic | None | Manual |
## Configuration
| Variable | Default | Description |
|----------|---------|-------------|
| `MEMORY_HOME` | `~/.memory` | Root directory for all memory data |
## Uninstall
```bash
/plugin uninstall claude-recap@claude-recap-marketplace
```
Your data in `~/.memory/` is preserved — uninstalling does not delete memory files. Reinstalling restores full functionality with existing data.
## Update
```bash
# Pull latest and update plugin cache
/plugin marketplace update claude-recap-marketplace
```
Or enable auto-update via `/plugin` → Marketplaces → "Enable auto-update".
## Documentation
- [Architecture](docs/architecture.md) — How the hooks, scripts, and cold-read pipeline work
- [Design Decisions](docs/design-decisions.md) — Why topic-based, why Markdown, why hooks
- [FAQ & Troubleshooting](docs/faq.md) — Common questions and solutions
- [Advanced Usage](docs/advanced-usage.md) — Custom storage, dev mode, manual setup
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).
## License
[MIT](LICENSE)