claude-recap

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)

# 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)

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