cc-memory

cc-memory

Claude Code persistent memory plugin — automatic LLM-powered save/restore of conversation context across compactions and sessions via SQLite + lifecycle hooks.

Problem

Claude Code compresses (compacts) conversations when the context window fills up, causing information loss: decisions, experiment results, task lists, and project knowledge disappear. Conversations that end normally (user closes terminal) also lose context.

Solution

cc-memory provides three layers of automatic memory capture so no important information is ever lost:

1. PreCompact (hook) — Before compaction, extracts structured memories from the full transcript using Haiku LLM API, saves to SQLite.
2. SessionStart (hook) — On any new session, (a) injects saved context into Claude's prompt, and (b) retroactively saves any previous unsaved transcripts.
3. /save-memories (skill) — Claude reviews the conversation with its own judgment and saves structured memories. Triggered manually or by CLAUDE.md rules.

Plus a Stop hook that reminds Claude to call /save-memories before the conversation ends.

Features

• LLM-powered extraction — Uses Claude Haiku API for high-quality, structured memory extraction
• OAuth auto-detection — Automatically reads Claude's own OAuth token from ~/.claude/.credentials.json (no separate API key needed)
• Token expiry checking — Validates OAuth token before use; warns when expired
• Retroactive save — SessionStart detects unsaved previous transcripts and extracts from them
• Save status notifications — SessionStart reports last auto-save result and API key status
• Zero information loss — Every conversation boundary (start/end/compaction) is covered
• Per-project — Each project gets its own memory/ directory with SQLite DB
• Structured memories — Categorized: decision, result, config, bug, task, architecture, note
• Importance scoring — 1-5 scale; critical (5) memories always survive
• Deduplication — All save paths check against existing memories before inserting
• Visual Dashboard — Tkinter GUI with memory management, plan execution, LLM-powered cleanup
• Project Registry — Persistent project list with add/remove/reorder/scan
• Plan Queue — Task planning system with Claude Code CLI execution
• CLI query tool — mem.py with full SQL access
• Standalone exe — PyInstaller-built executables for one-click install and dashboard
• Zero-dependency runtime — Pure Python stdlib (sqlite3, json, pathlib, tkinter, urllib)

Installation

Option 1: Standalone exe (recommended for Windows)

1. Download cc-memory-installer.exe from Releases
2. Double-click to run
3. Click "Install Plugin" → "Configure Hooks" → select project → "Initialize Project"

Option 2: From source

# Clone the repo
git clone https://github.com/skymanbp/cc-memory.git

# Run the installer GUI
python cc-memory/cc_memory/installer.py

# Or CLI setup
python cc-memory/cc_memory/setup.py

# Initialize a project
python cc-memory/cc_memory/setup.py --init /path/to/your/project

The installer will:

1. Copy hook scripts to ~/.claude/hooks/cc-memory/
2. Add PreCompact + SessionStart + Stop hooks to ~/.claude/settings.json
3. Create memory/ directory in the specified project

API Key (automatic)

cc-memory auto-detects your Claude OAuth token from ~/.claude/.credentials.json. No manual API key setup is needed if you're logged into Claude Code.

If auto-detection fails (e.g., running outside Claude Code), you can:

# Set env var manually
setx ANTHROPIC_API_KEY "sk-ant-..."   # Windows
export ANTHROPIC_API_KEY="sk-ant-..."  # Linux/macOS

# Or use the Dashboard Settings dialog

API key resolution order: manual setting → ANTHROPIC_API_KEY env var → Claude OAuth token

Optional: /save-memories skill

Copy the skill template into any project for Claude-judged memory saves:

mkdir -p <project>/.claude/skills/save-memories
cp cc_memory/skill_template.md <project>/.claude/skills/save-memories/SKILL.md

Then invoke with /save-memories during any conversation, or add a CLAUDE.md rule to auto-trigger it.

Architecture

Global (installed once, shared by all projects)
├── ~/.claude/hooks/cc-memory/     ← Plugin code (14 .py files + config.json)
├── ~/.claude/settings.json        ← Hook trigger configuration
└── ~/.claude/.credentials.json    ← OAuth token (read-only, managed by Claude Code)