Advanced Configuration - robwhite4/claude-memory GitHub Wiki

Advanced Configuration

This guide covers advanced configuration options for Claude Memory to customize its behavior for your specific needs.

Configuration Overview

Claude Memory stores configuration in .claude/config.json with sensible defaults that work for most projects. You can customize behavior through:

Configuration commands
Configuration file editing
Environment variables
CLI flags

Default Configuration

The actual default configuration includes these settings:

{
  "autoSession": true,              // Automatic session management
  "autoSessionHours": 4,            // Hours per session rotation
  "autoBackup": true,               // Automatic backup system
  "backupInterval": 10,             // Actions before auto-backup
  "maxBackupDays": 7,               // Days to keep backups (legacy: backupRetentionDays)
  "tokenOptimization": true,        // Optimize CLAUDE.md size
  "silentMode": false               // Suppress output messages
}

Setting Configuration

Using Commands

# View all settings
cmem config get

# View specific setting
cmem config get autoSession

# Update setting
cmem config set autoSessionHours 6
cmem config set tokenOptimization false
cmem config set silentMode true

# Parse boolean and numeric values automatically
cmem config set autoBackup true    # Boolean
cmem config set backupInterval 20   # Number

Direct File Editing

# Edit configuration file
nano .claude/config.json

# Make changes and save
# Claude Memory will use the updated config next time it runs

Note: Currently there are no config reset or config validate commands. To reset, delete the config file and reinitialize.

Environment Variables

Override configuration with environment variables:

# Override config file location
export CLAUDE_MEMORY_CONFIG=/path/to/custom-config.json

# Enable debug mode
export CLAUDE_MEMORY_DEBUG=true

# Use in one-time commands
CLAUDE_MEMORY_FORCE=true cmem session cleanup

CLI Flags

Global flags override both config and environment:

# Available global flags (v1.9.0)
cmem stats --dry-run       # Preview changes without executing
cmem stats --config ~/custom-config.json  # Use custom config file
cmem session cleanup --force              # Skip confirmation prompts
cmem stats --debug                        # Show detailed debug info
cmem --version                            # Display version
cmem task list --quiet                    # Suppress non-essential output
cmem task list --output json              # Output format (json/yaml/text)
cmem help --no-color                      # Disable colored output
cmem stats --verbose                      # Show detailed information

# Combine multiple flags
cmem task complete abc123 --force --quiet

Session Management

The automatic session management uses these periods by default:

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

To customize session duration:

# Change to 8-hour sessions
cmem config set autoSessionHours 8

# Disable automatic sessions
cmem config set autoSession false

Backup Configuration

Configure automatic backups:

# Change backup frequency (number of actions)
cmem config set backupInterval 5

# Change retention period (days)
cmem config set maxBackupDays 14

# Disable automatic backups
cmem config set autoBackup false

Backups are stored in .claude/backups/ with timestamps.

Token Optimization

When enabled, Claude Memory automatically optimizes CLAUDE.md to stay under ~3000 tokens by:

Prioritizing current session information
Including recent decisions and active tasks
Limiting historical data
Referencing full context files for details

# Disable token optimization (keep full context)
cmem config set tokenOptimization false

Silent Mode

Reduce output verbosity:

# Enable silent mode
cmem config set silentMode true

# Or use --quiet flag for one command
cmem stats --quiet

Use Case Configurations

Minimal Setup (CI/CD)

{
  "autoSession": false,
  "autoBackup": false,
  "tokenOptimization": true,
  "silentMode": true
}

Long Work Sessions

{
  "autoSession": true,
  "autoSessionHours": 8,
  "autoBackup": true,
  "backupInterval": 20,
  "tokenOptimization": true
}

Maximum Context Preservation

{
  "autoSession": true,
  "autoSessionHours": 4,
  "autoBackup": true,
  "backupInterval": 5,
  "maxBackupDays": 30,
  "tokenOptimization": false
}

Debug Mode

Enable debug mode to troubleshoot issues:

# Via environment variable
export CLAUDE_MEMORY_DEBUG=true

# Via CLI flag
cmem stats --debug

Debug mode shows:

File paths being used
Configuration loading
Timing information
Detailed operation logs

Custom Configuration File

Use a custom configuration file:

# Via environment variable (persistent)
export CLAUDE_MEMORY_CONFIG=~/my-configs/project-config.json

# Via CLI flag (one-time)
cmem init --config ~/my-configs/project-config.json

Best Practices

Start with defaults - They work well for most projects
Adjust gradually - Change one setting at a time
Use flags for testing - Try changes with CLI flags before saving
Document custom settings - Add comments in a separate file
Version control considerations - .claude/config.json is gitignored by default

Troubleshooting Configuration

Config Not Loading

# Check current config
cmem config get

# Verify file location
ls -la .claude/config.json

# Check for syntax errors in JSON
python -m json.tool .claude/config.json

Settings Not Taking Effect

Ensure you're in the correct project directory
Check for environment variable overrides
Verify no CLI flags are overriding settings