Configuration

Environment Variables

Variable	Default	Description
`CLAUDE_PLUGIN_ROOT`	Set by Claude Code	Plugin installation directory
`CLAUDE_MEM_DATA_DIR`	`~/.claude-mem/`	Data directory (production default)
`CLAUDE_CODE_PATH`	Auto-detected	Path to Claude Code CLI (for Windows)
`CLAUDE_MEM_WORKER_PORT`	`37777`	Worker service port
`CLAUDE_MEM_MODEL`	`claude-sonnet-4-5`	AI model for processing observations
`CLAUDE_MEM_CONTEXT_OBSERVATIONS`	`50`	Number of observations to inject
`NODE_ENV`	`production`	Environment mode
`FORCE_COLOR`	`1`	Enable colored logs

Model Configuration

Configure which AI model processes your observations.

Available Models

claude-haiku-4-5 - Fast, cost-efficient
claude-sonnet-4-5 - Balanced (default)
claude-opus-4 - Most capable
claude-3-7-sonnet - Alternative version

Using the Interactive Script

./claude-mem-settings.sh

This script manages CLAUDE_MEM_MODEL in ~/.claude/settings.json.

Manual Configuration

Edit ~/.claude/settings.json:

{
  "CLAUDE_MEM_MODEL": "claude-sonnet-4-5"
}

Files and Directories

Data Directory Structure

The data directory location depends on the environment:

Production (installed plugin): ~/.claude-mem/ (always, regardless of CLAUDE_PLUGIN_ROOT)
Development: Can be overridden with CLAUDE_MEM_DATA_DIR

~/.claude-mem/
├── claude-mem.db           # SQLite database
├── .install-version        # Cached version for smart installer
├── worker.port             # Current worker port file
└── logs/
    ├── worker-out.log      # Worker stdout logs
    └── worker-error.log    # Worker stderr logs

Plugin Directory Structure

${CLAUDE_PLUGIN_ROOT}/
├── .claude-plugin/
│   └── plugin.json         # Plugin metadata
├── .mcp.json               # MCP server configuration
├── hooks/
│   └── hooks.json          # Hook configuration
├── scripts/                # Built executables
│   ├── smart-install.js    # Smart installer script
│   ├── context-hook.js     # Context injection hook
│   ├── new-hook.js         # Session creation hook
│   ├── save-hook.js        # Observation capture hook
│   ├── summary-hook.js     # Summary generation hook
│   ├── cleanup-hook.js     # Session cleanup hook
│   ├── worker-service.cjs  # Worker service (CJS)
│   └── search-server.mjs   # MCP search server (ESM)
└── ui/
    └── viewer.html         # Web viewer UI bundle

Plugin Configuration

Hooks Configuration

Hooks are configured in plugin/hooks/hooks.json:

{
  "description": "Claude-mem memory system hooks",
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/smart-install.js && node ${CLAUDE_PLUGIN_ROOT}/scripts/context-hook.js",
        "timeout": 120
      }]
    }],
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/new-hook.js",
        "timeout": 120
      }]
    }],
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/save-hook.js",
        "timeout": 120
      }]
    }],
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/summary-hook.js",
        "timeout": 120
      }]
    }],
    "SessionEnd": [{
      "hooks": [{
        "type": "command",
        "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/cleanup-hook.js",
        "timeout": 120
      }]
    }]
  }
}

Search Configuration (v5.4.0+)

Migration Note: As of v5.4.0, Claude-Mem uses skill-based search instead of MCP tools. Previous (v5.3.x and earlier): MCP search server with 9 tools (~2,500 tokens per session) Current (v5.4.0+): Search skill with HTTP API (~250 tokens per session) No configuration required - the search skill is automatically available in Claude Code sessions. Search operations are now provided via:

Skill: plugin/skills/search/SKILL.md (auto-invoked when users ask about past work)
HTTP API: 10 endpoints on worker service port 37777
Progressive Disclosure: Full instructions loaded on-demand only when needed

PM2 Configuration

Worker service is managed by PM2 via ecosystem.config.cjs:

module.exports = {
  apps: [{
    name: 'claude-mem-worker',
    script: './plugin/scripts/worker-service.cjs',
    instances: 1,
    autorestart: true,
    watch: false,
    max_memory_restart: '1G',
    env: {
      NODE_ENV: 'production',
      FORCE_COLOR: '1'
    }
  }]
};

PM2 Settings

instances: 1 (single instance)
autorestart: true (auto-restart on crash)
watch: false (no file watching)
max_memory_restart: 1G (restart if memory exceeds 1GB)

Context Injection Configuration

CLAUDE_MEM_CONTEXT_OBSERVATIONS

Controls how many observations are injected into each new session for context continuity. Default: 50 observations What it does:

Fetches the most recent N observations from the database
Injects them as context at SessionStart
Allows Claude to maintain awareness of recent work across sessions

Configuration in ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "100"
  }
}

Considerations:

Higher values = More context but slower SessionStart and more tokens used
Lower values = Faster SessionStart but less historical awareness
Default of 50 balances context richness with performance

Note: This injects individual observations, not entire sessions. Each observation represents a single tool execution (Read, Write, Edit, etc.) that was compressed into a semantic learning.

Customization

Custom Data Directory

For development or testing, override the data directory:

export CLAUDE_MEM_DATA_DIR=/custom/path

Custom Worker Port

If port 37777 is in use:

export CLAUDE_MEM_WORKER_PORT=38000
npm run worker:restart

Custom Model

Use a different AI model:

export CLAUDE_MEM_MODEL=claude-opus-4
npm run worker:restart

Advanced Configuration

Hook Timeouts

Modify timeouts in plugin/hooks/hooks.json:

{
  "timeout": 120  // Default: 120 seconds
}

Recommended values:

SessionStart: 120s (needs time for smart install check and context retrieval)
UserPromptSubmit: 60s
PostToolUse: 120s (can process many observations)
Stop: 60s
SessionEnd: 60s

Note: With smart install caching (v5.0.3+), SessionStart is typically very fast (10ms) unless dependencies need installation.

Worker Memory Limit

Modify PM2 memory limit in ecosystem.config.cjs:

{
  max_memory_restart: '2G'  // Increase if needed
}

Logging Verbosity

Enable debug logging:

export DEBUG=claude-mem:*
npm run worker:restart
npm run worker:logs

Configuration Best Practices

Use defaults: Default configuration works for most use cases
Override selectively: Only change what you need
Document changes: Keep track of custom configurations
Test after changes: Verify worker restarts successfully
Monitor logs: Check worker logs after configuration changes

Troubleshooting Configuration

Configuration Not Applied

Restart worker after changes:
```
npm run worker:restart
```

Verify environment variables:

echo $CLAUDE_MEM_MODEL
echo $CLAUDE_MEM_WORKER_PORT

Check worker logs:
```
npm run worker:logs
```

Invalid Model Name

If you specify an invalid model name, the worker will fall back to claude-sonnet-4-5 and log a warning. Valid models:

claude-haiku-4-5
claude-sonnet-4-5
claude-opus-4
claude-3-7-sonnet

Port Already in Use

If port 37777 is already in use:

Set custom port:
```
export CLAUDE_MEM_WORKER_PORT=38000
```
Restart worker:
```
npm run worker:restart
```
Verify new port:
```
cat ~/.claude-mem/worker.port
```

Next Steps

Architecture Overview - Understand the system
Troubleshooting - Common issues
Development - Building from source

Get Started

Best Practices

Configuration & Development

Architecture

Configuration

Configuration

Environment Variables

Model Configuration

Available Models

Using the Interactive Script

Manual Configuration

Files and Directories

Data Directory Structure

Plugin Directory Structure

Plugin Configuration

Hooks Configuration

Search Configuration (v5.4.0+)

PM2 Configuration

PM2 Settings

Context Injection Configuration

CLAUDE_MEM_CONTEXT_OBSERVATIONS

Customization

Custom Data Directory

Custom Worker Port

Custom Model

Advanced Configuration

Hook Timeouts

Worker Memory Limit

Logging Verbosity

Configuration Best Practices

Troubleshooting Configuration

Configuration Not Applied

Invalid Model Name

Port Already in Use

Next Steps

Get Started

Best Practices

Configuration & Development

Architecture

​Configuration

​Environment Variables

​Model Configuration

​Available Models

​Using the Interactive Script

​Manual Configuration

​Files and Directories

​Data Directory Structure

​Plugin Directory Structure

​Plugin Configuration

​Hooks Configuration

​Search Configuration (v5.4.0+)

​PM2 Configuration

​PM2 Settings

​Context Injection Configuration

​CLAUDE_MEM_CONTEXT_OBSERVATIONS

​Customization

​Custom Data Directory

​Custom Worker Port

​Custom Model

​Advanced Configuration

​Hook Timeouts

​Worker Memory Limit

​Logging Verbosity

​Configuration Best Practices

​Troubleshooting Configuration

​Configuration Not Applied

​Invalid Model Name

​Port Already in Use

​Next Steps

Configuration

Environment Variables

Model Configuration

Available Models

Using the Interactive Script

Manual Configuration

Files and Directories

Data Directory Structure

Plugin Directory Structure

Plugin Configuration

Hooks Configuration

Search Configuration (v5.4.0+)

PM2 Configuration

PM2 Settings

Context Injection Configuration

CLAUDE_MEM_CONTEXT_OBSERVATIONS

Customization

Custom Data Directory

Custom Worker Port

Custom Model

Advanced Configuration

Hook Timeouts

Worker Memory Limit

Logging Verbosity

Configuration Best Practices

Troubleshooting Configuration

Configuration Not Applied

Invalid Model Name

Port Already in Use

Next Steps