Claude Memory System

Automatic AI context management that works silently in the background

🚀 Latest Release: v1.11.0

New Features:

• Summary Management - Create, list, and view project summaries
• Bug Fixes - Knowledge counts update immediately, handoff saves to HANDOFF.md

🤖 Set and Forget

Claude Memory runs automatically in the background, maintaining perfect context for AI assistants without any manual intervention.

# Install once
npm install -g claude-memory

# Initialize and forget
cmem init

# That's it! Claude now has persistent memory

🎯 The Problem It Solves

Without Claude Memory - Every conversation starts from zero:

You: "Continue working on the auth system"
AI: "What framework? What auth method? Where are the files?"
You: *10 minutes explaining everything again...*

With Claude Memory - AI knows your project instantly:

You: "Continue working on the auth system" 
AI: "I see you're using NextAuth with JWT. Last session you completed 
the login flow. The remaining tasks are password reset and 2FA. 
Should I start with the password reset endpoint you stubbed in 
/api/auth/reset.ts?"

🪄 How It Works (Automatically)

1. Auto-Session Management

Sessions start and rotate automatically every 4 hours, organizing your work by time of day:

• Morning Development (6am-12pm)
• Afternoon Development (12pm-5pm)
• Evening Development (5pm-9pm)
• Night Development (9pm-6am)

2. Auto-Backups

Your project memory is automatically backed up:

• After every 10 significant actions
• When sessions rotate
• Daily on first activity
• Keeps 7 days of history

3. Token-Optimized Context

CLAUDE.md is automatically optimized to include only:

• Current session info
• Recent decisions (last 3-5)
• Active tasks and high-priority items
• Recent completions for continuity
• Critical patterns only

4. Zero Configuration

Default settings work perfectly for most projects:

{
  "autoSession": true,
  "autoSessionHours": 4,
  "autoBackup": true,
  "backupInterval": 10,
  "tokenOptimization": true
}

📦 What Gets Created

your-project/
├── CLAUDE.md          # AI-readable project context (commit this!)
└── .claude/           # Auto-generated memory system
    ├── memory.json    # Full memory database
    ├── config.json    # Your preferences  
    ├── backups/       # Automatic backups
    └── context/       # Full context files (v1.7.0+)
        ├── knowledge.md   # Complete knowledge base
        ├── patterns.md    # All patterns with details
        ├── decisions.md   # Full decision history
        └── tasks.md       # Detailed task information

Version Control:

• ✅ Commit: CLAUDE.md - This is your project's AI context
• ❌ Don't commit: .claude/ directory - Contains generated files and personal preferences
• 💡 Optional: You can commit .claude/context/ if you want to share full project knowledge with your team

🔄 Multi-Machine & Team Development

Working Across Multiple Machines

If you work on multiple computers, commit the context files to sync your memory:

# In your .gitignore, change this:
.claude/

# To this (keeping config and raw data local):
.claude/sessions/
.claude/backups/
.claude/memory.json
.claude/config.json
!.claude/context/

📁 See more .gitignore templates for different team setups.

Workflow:

1. git pull - Get latest memory from other machine
2. Work and update memory with cmem commands
3. git add . && git commit - Include memory updates
4. git push - Share memory with other machines

Team Development

Claude Memory can work for teams with some considerations:

Best for:

• Shared project knowledge and decisions
• Onboarding new developers
• AI-assisted development handoffs

Potential Issues:

• Merge conflicts in context files (auto-generated)
• Personal patterns mixed with team patterns

Recommended Team Approach:

1. Designate a Memory Keeper - One person updates project memory

2. Use PR Descriptions - Document decisions in PRs instead

3. Team Conventions:

   # Prefix patterns for clarity
   cmem pattern add "[TEAM] Code review required" "..." 
   cmem pattern add "[ALICE] Personal debugging" "..."
      
   # Use categories
   cmem knowledge add "API_v2_Design" "..." --category architecture

4. Handle Merge Conflicts:

   # Accept incoming changes and regenerate
   git checkout --theirs .claude/context/
   cmem knowledge add "merge_note" "Merged from main"

🚀 Basic Usage (Manual Commands)

While Claude Memory works automatically, you can also use manual commands:

# Check what Claude knows
cmem stats

# Add important decisions
cmem decision "Use PostgreSQL" "Need ACID compliance" "MongoDB,DynamoDB"

# Track patterns
cmem pattern "API-first design" "Build APIs before UI" 0.9 high

# Manage tasks
cmem task add "Implement user settings" --priority high
cmem task complete abc123 "Added settings page"

# Bulk task operations (v1.10.0+)
cmem task add-bulk tasks.json
cmem task export github pending

# Enhanced export and reporting (v1.10.0+)
cmem export --format yaml --types tasks,patterns --from 2024-01-01
cmem import backup.json --mode merge
cmem report summary --save
cmem report sprint --format markdown

# Search your memory
cmem search "authentication"

🔧 Claude-Code Integration

For claude-code users, memory is automatically included:

# Get current context as JSON
cmem context

# Returns:
{
  "session": "Afternoon Development",
  "activeTasks": [...],
  "recentDecisions": [...],
  "openPatterns": [...]
}

This context is automatically injected into your Claude conversations, giving perfect continuity without any extra tokens or manual steps.

💰 Token Efficiency

Claude Memory significantly reduces token usage by eliminating repeated context. The token optimization feature intelligently manages context size while preserving critical information.

Typical savings scenarios:

• Quick questions about ongoing work: Minimal context needed, maximum savings
• Continuing previous sessions: No need to re-explain project structure or decisions
• Team handoffs: Shared context eliminates lengthy explanations

When token optimization is enabled (default), CLAUDE.md stays concise while maintaining full context in the memory system.

📂 Multi-File Context System (v1.7.0+)

Claude Memory now preserves complete information without truncation through a multi-file context system:

How It Works

• CLAUDE.md: Remains the primary context file, optimized for tokens
• Context Files: Full details stored in .claude/context/ directory
• No Information Loss: Everything is preserved, just better organized

Context Files

• knowledge.md: Complete knowledge base with all values untruncated
• patterns.md: All patterns with full descriptions and history
• decisions.md: Complete decision log with reasoning and outcomes
• tasks.md: Detailed task information including assignments and dates

Benefits

• Full Context Access: AI can read specific context files when needed
• Token Efficient: Main CLAUDE.md stays under 3K tokens
• Human Readable: Well-organized markdown files for easy browsing
• Git Friendly: Context files can be tracked or ignored as needed

The CLAUDE.md file includes references to these context files, allowing AI assistants to request more detailed information when necessary.

🛠️ Configuration

Adjust behavior if needed:

# View current config
cmem config get

# Adjust settings
cmem config set autoSessionHours 6
cmem config set tokenOptimization false
cmem config set silentMode true

🏗️ Code Structure

The codebase is organized into modular components for maintainability:

claude-memory/
├── bin/
│   └── claude-memory.js     # CLI entry point (1,770 lines)
├── lib/
│   ├── ClaudeMemory.js      # Core memory management (1,016 lines)
│   └── utils/
│       ├── validators.js     # Input validation functions
│       ├── sanitizers.js     # Security sanitization
│       └── formatters.js     # Output formatting
└── package.json              # NPM configuration

This modular structure makes the codebase easier to maintain and extend while preserving all functionality.

🚩 Global CLI Flags

Control Claude Memory behavior with these global flags:

# Preview changes without executing
cmem task add "New feature" --dry-run

# Use custom configuration file
cmem init "Project" --config ~/my-config.json
export CLAUDE_MEMORY_CONFIG=~/my-config.json  # Or via environment

# Skip confirmation prompts
cmem session cleanup --force

# Debug execution issues
cmem stats --debug

# Control output format
cmem search "bug" --output json
cmem stats --quiet  # Suppress non-essential output
cmem help --no-color  # Disable colors for CI/CD

Available flags:

• --dry-run - Preview changes without making them
• --config <path> - Use custom config file
• --force - Skip confirmation prompts
• --debug - Show detailed execution info
• --quiet - Suppress non-essential output
• --output <format> - Output format (json/yaml/text)
• --no-color - Disable colored output
• --verbose - Show detailed information

📊 Advanced Features

Pattern Resolution

# Learn from problems
cmem pattern "Memory leak in useEffect" "Always cleanup subscriptions" 1.0 critical

# Document solutions
cmem pattern resolve abc123 "Added cleanup function to all effects"

Session Control

# Manual session management (optional)
cmem session start "Feature: Payment Integration"
cmem session end "Completed Stripe integration"

# View history
cmem session list

Import/Export (v1.10.0)

# Export memory - supports JSON, YAML, CSV, Markdown formats
cmem export backup.json                    # Full backup
cmem export report.md --format markdown    # Human-readable report
cmem export --types tasks,patterns         # Specific data types
cmem export --from 2024-01-01 --sanitized # Date range + sanitized

# Import memory - merge or replace modes
cmem import backup.json                    # Merge by default
cmem import fresh.json --mode replace      # Replace existing
cmem import tasks.yaml --dry-run          # Preview changes

# Bulk operations
cmem task add-bulk tasks.json             # Import multiple tasks
cmem task export json > tasks.json        # Export for backup

Report Generation (v1.10.0)

# Generate reports - summary, tasks, patterns, decisions, progress, sprint
cmem report                                # Default summary
cmem report sprint --save                  # Auto-timestamped
cmem report tasks --from 2024-01-01       # Date filtering
cmem report --format json --save           # JSON output

Summary Management (v1.11.0)

# Create contextual summaries
cmem summary generate "Sprint Retrospective"              # With current session
cmem summary generate "Release" --session morning-dev     # Specific session
cmem summary list                                         # List all summaries
cmem summary view 2025-01-15-sprint-retrospective        # View content

AI Assistant Handoffs

# Generate handoff summary (saves to HANDOFF.md)
cmem handoff                       # Comprehensive summary
cmem handoff --stdout              # Output to console
cmem handoff --format=json         # JSON format

🔄 Workflow Examples

Daily Development Flow

# Morning - Memory handles everything automatically
$ cd my-project
$ echo "Continue where I left off yesterday"
# Claude reads CLAUDE.md, knows exactly what you were doing

# Make decisions - Memory captures them
$ cmem decision "Switch to TypeScript" "Type safety for scale" "Keep JS"

# Track progress - Memory maintains context  
$ cmem task complete task-123 "Refactored auth module"

# Evening - Memory auto-rotates session with summary
# Everything saved, backed up, and ready for tomorrow

Team Collaboration

# Developer A works on auth
$ cmem session start "Auth System Implementation"
# ... work happens, patterns learned, decisions made ...

# Developer B picks up the next day
$ cat CLAUDE.md  # Sees auth decisions, patterns, progress
$ echo "Continue auth implementation"
# Claude knows exactly what Developer A did

🎯 Best Practices

1. Commit CLAUDE.md - Share team knowledge
2. Don't worry about sessions - They manage themselves
3. Document decisions - Future you will thank you
4. Track patterns - Claude learns and improves
5. Let it run - The magic happens automatically

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

• 🐛 Report bugs
• 💡 Request features
• 📖 Read contribution guidelines
• 📜 View code of conduct

📄 License

MIT © Rob White

Stop explaining your project over and over. Install Claude Memory and let AI truly understand your codebase.

npm install -g claude-memory && cmem init