ccmem - Claude Code Memory System
A file-based memory system for Claude Code that learns from observations and improves over time.
Installation
As Claude Code Plugin (Recommended)
# Add the plugin marketplace
/plugin marketplace add /path/to/ccmem
# Install the plugin
/plugin install ccmem@ccmem-dev
# Restart Claude Code to activate
Manual Installation
# Clone or copy to ~/.claude/memory/
# Set up hooks in Claude Code settings
CLI Setup (Optional)
To use the ccmem CLI directly from your terminal, add the plugin's bin directory to your PATH:
# Find where the plugin is installed
CCMEM_PATH=$(find ~/.claude/plugins -name "ccmem" -type f -path "*/bin/*" 2>/dev/null | head -1 | xargs dirname)
# Add to your shell profile (~/.zshrc or ~/.bashrc)
export PATH="$CCMEM_PATH:$PATH"
Alternatively, use slash commands in Claude Code (no PATH setup needed):
/ccmem-stats — View statistics/ccmem-list — List memories/ccmem-search <query> — Search memories/ccmem-show <id> — Show memory details/ccmem-remember <description> — Create a memory/ccmem-reinforce <id> — Positive feedback/ccmem-correct <id> — Negative feedback/ccmem-promote — Review and promote to CLAUDE.md/ccmem-cleanup — Review low-confidence memories
Quick Start
# View statistics
ccmem stats
# Search memories
ccmem search "pnpm"
ccmem search "workflow"
# List all memories
ccmem list
# Show specific memory
ccmem show <memory-id>
# Provide feedback
ccmem reinforce <memory-id> # Positive feedback
ccmem correct <memory-id> # Negative feedback
# Run maintenance manually
ccmem maintenance
# Check automation status
ccmem automation status
# Unload automation
ccmem automation unload
Orphaned Session Recovery
If Claude Code crashes or is killed abruptly (terminal closed, process killed), sessions may be left without a proper session_end event. The system automatically detects and recovers these orphaned sessions:
- Recovery happens at the start of each new session
- Orphaned sessions are finalized with synthetic
session_end events
- Marked with
"recovered": true in sessions.json
- Current active session is never recovered
Configuration
Set CLAUDE_MEMORY_DIR environment variable to customize where memory data is stored:
export CLAUDE_MEMORY_DIR="/custom/path/to/memory"
Default: ~/.claude/memory/
Directory Structure
~/.claude/memory/
├── config.json # System configuration
├── index.json # Master memory index
├── observations.jsonl # Event stream (hooks write here)
├── feedback.jsonl # User feedback log
├── search-index.json # Full-text search index
├── memories/
│ ├── global/ # Global memories
│ └── projects/ # Per-project memories
├── hooks/ # Claude Code hooks
├── scripts/ # Utility scripts
├── skills/ # Claude Code skills
└── bin/ # CLI commands
How It Works
- Capture: Hooks capture session events (prompts, tool uses) to
observations.jsonl
- Analyze: The analyzer detects patterns and creates memory files
- Retrieve: The system searches relevant memories based on context
- Learn: Feedback adjusts confidence; unused memories decay over time
- Sync: High-confidence memories (≥0.8) automatically sync to CLAUDE.md
CLAUDE.md Integration
High-confidence memories (≥0.8) are automatically synced to your CLAUDE.md file at session start:
<!-- memory-sync: start -->
<!-- These sections are auto-updated from high-confidence memories -->
### Active Memories (High Confidence)
- prefer-pnpm-over-npm (0.85) — Suggest pnpm for Node.js projects
- prefer-task-based-workflow (0.90) — Use TodoWrite for complex tasks
...
<!-- memory-sync: end -->
How it works:
- The
on-start.sh hook automatically runs ccmem sync --promote
- Memories with confidence ≥0.8 are formatted and inserted between sync markers
- Manual sections outside sync markers are preserved
- Memories can be reinforced (
ccmem reinforce) or corrected (ccmem correct)
Manual sync:
# Promote high-confidence memories to CLAUDE.md
ccmem sync --promote
# Import CLAUDE.md rules back to memories
ccmem sync --import
# Two-way sync
ccmem sync
Automation
Option 1: Launch Agent (macOS)
# Install the launch agent
cp ~/.claude/memory/com.elche.memory-maintenance.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.elche.memory-maintenance.plist
# Verify it's loaded
launchctl list | grep memory-maintenance
Runs daily at midnight.
Option 2: Cron (Linux/macOS)
# Edit crontab
crontab -e
# Add line for daily maintenance at 2 AM
0 2 * * * ~/.claude/memory/scripts/maintenance.sh run
Option 3: Manual
Run maintenance whenever convenient:
ccmem maintenance