Troubleshooting

This guide helps you resolve common issues with Claude Memory.

Installation Issues

Command Not Found

After installing Claude Memory, if cmem is not recognized:

# Check if npm global bin is in PATH
npm bin -g

# Add to PATH (add to .bashrc, .zshrc, or equivalent)
export PATH="$(npm bin -g):$PATH"

# Reload shell configuration
source ~/.bashrc  # or ~/.zshrc

Permission Errors

If you encounter permission errors during installation:

# Option 1: Configure npm to use a different directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install -g claude-memory

# Option 2: Use a Node version manager (recommended)
# Install nvm, then:
nvm install node
npm install -g claude-memory

Version Conflicts

If you have an older version causing issues:

# Check current version
cmem --version

# Uninstall old version
npm uninstall -g claude-memory

# Clear npm cache
npm cache clean --force

# Install latest version
npm install -g claude-memory@latest

Runtime Issues

Memory File Corruption

If memory.json becomes corrupted:

# Claude Memory creates automatic backups
cd .claude/backups/

# List available backups
ls -la

# Restore from backup
cp memory_2024-01-15T10-30-00.json ../memory.json

# Verify restoration
cmem stats

Session Not Rotating

If sessions aren't rotating automatically:

# Check auto-session setting
cmem config get autoSession

# Enable if disabled
cmem config set autoSession true

# Check session hours setting
cmem config get autoSessionHours

# Manually end current session if needed
cmem session end "Manual rotation"

High Memory Usage

If CLAUDE.md is getting too large:

# Check current token usage
cmem stats

# Enable token optimization
cmem config set tokenOptimization true

# Token optimization is binary on/off
# To reduce context, clean up old data instead

# Clean up old sessions
cmem session cleanup

Command Issues

Task Command Fails

If task commands aren't working:

# Check task list format
cmem task list --debug

# If tasks are corrupted, export and reimport
cmem export backup.json
# Edit backup.json to fix issues
# Manually restore from backup
cp .claude/backups/backup-timestamp.json .claude/memory.json

Search Returns No Results

If search isn't finding expected content:

# Check if content exists
cmem stats

# Try broader search terms
cmem search "auth"  # instead of "authentication"

# Search in specific areas
cmem search "auth"  # Searches all memory types
cmem pattern search "auth"
cmem task list  # Then manually look for auth tasks

Pattern Resolution Fails

If you can't resolve patterns:

# List all patterns with IDs
cmem pattern list

# Use exact ID (not partial)
cmem pattern resolve abc123def456 "Solution description"

# If ID is lost, search for pattern
cmem pattern search "pattern description"

Configuration Issues

Config Not Persisting

If configuration changes aren't saved:

# Check config file permissions
ls -la .claude/config.json

# Set with explicit save
cmem config set autoBackup true --force

# Verify change
cmem config get autoBackup

Environment Variables Not Working

If CLAUDE_MEMORY_CONFIG isn't recognized:

# Use absolute path
export CLAUDE_MEMORY_CONFIG="$HOME/my-project/custom-config.json"

# Or use --config flag
cmem stats --config ~/custom-config.json

Integration Issues

CLAUDE.md Not Updating

If CLAUDE.md isn't reflecting changes:

# Force regeneration
cmem context --force

# Check file permissions
ls -la CLAUDE.md

# Manually trigger update
cmem task add "Trigger update" && cmem task list

Git Conflicts in Team Setup

If you get merge conflicts in context files:

# Accept incoming changes
git checkout --theirs .claude/context/

# Regenerate local context
cmem knowledge add "merge_note" "Merged from main branch"

# Or keep local and update
git checkout --ours .claude/context/
cmem context --force

Debug Mode

For any issue, enable debug mode for detailed information:

# One-time debug
cmem stats --debug

# Enable debug for session
export CLAUDE_MEMORY_DEBUG=true

# Debug specific command
cmem task list --debug > debug-output.txt

Common Error Messages

"ENOENT: no such file or directory"

# Initialize project first
cmem init

# Or specify project directory
cmem init "My Project" --path /path/to/project

"Invalid task ID"

# List tasks with full IDs
cmem task list --verbose

# Use exact ID shown
cmem task complete abc123def456

"Memory limit exceeded"

# Clean up old data
cmem session cleanup

# Clean up old sessions instead
cmem session cleanup --force

Manual Recovery

If all else fails, you can manually edit the memory files:

# Backup current state
cp -r .claude .claude.backup

# Edit memory file
nano .claude/memory.json

# Validate JSON
python -m json.tool .claude/memory.json

# Test recovery
cmem stats

Getting Help

If you're still experiencing issues:

1. Check the GitHub Issues
2. Enable debug mode and capture output
3. Create a new issue with:
   • Claude Memory version (cmem --version)
   • Node.js version (node --version)
   • Error message and debug output
   • Steps to reproduce

---

Quick Fixes

# Reinstall
npm install -g claude-memory@latest

# Reset project
rm -rf .claude && cmem init

# Force update context
cmem context --force

# Check everything
cmem stats --debug