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

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

/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

# Pull latest and update plugin cache
/plugin marketplace update claude-recap-marketplace

Or enable auto-update via /plugin → Marketplaces → "Enable auto-update".

Documentation

• Architecture — How the hooks, scripts, and cold-read pipeline work
• Design Decisions — Why topic-based, why Markdown, why hooks
• FAQ & Troubleshooting — Common questions and solutions
• Advanced Usage — Custom storage, dev mode, manual setup

Contributing

See CONTRIBUTING.md.

License

MIT