ccmem

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

1. Capture: Hooks capture session events (prompts, tool uses) to observations.jsonl
2. Analyze: The analyzer detects patterns and creates memory files
3. Retrieve: The system searches relevant memories based on context
4. Learn: Feedback adjusts confidence; unused memories decay over time
5. 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