claude-mem/docs/configuration.mdx

---
title: "Configuration"
description: "Environment variables and settings for Claude-Mem"
---

# 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

```bash
./claude-mem-settings.sh
```

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

### Manual Configuration

Edit `~/.claude/settings.json`:

```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`:

```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`:

```javascript
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`:

```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:

```bash
export CLAUDE_MEM_DATA_DIR=/custom/path
```

### Custom Worker Port

If port 37777 is in use:

```bash
export CLAUDE_MEM_WORKER_PORT=38000
npm run worker:restart
```

### Custom Model

Use a different AI model:

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

## Advanced Configuration

### Hook Timeouts

Modify timeouts in `plugin/hooks/hooks.json`:

```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`:

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

### Logging Verbosity

Enable debug logging:

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

## Configuration Best Practices

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

## Troubleshooting Configuration

### Configuration Not Applied

1. Restart worker after changes:
   ```bash
   npm run worker:restart
   ```

2. Verify environment variables:
   ```bash
   echo $CLAUDE_MEM_MODEL
   echo $CLAUDE_MEM_WORKER_PORT
   ```

3. Check worker logs:
   ```bash
   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:

1. Set custom port:
   ```bash
   export CLAUDE_MEM_WORKER_PORT=38000
   ```

2. Restart worker:
   ```bash
   npm run worker:restart
   ```

3. Verify new port:
   ```bash
   cat ~/.claude-mem/worker.port
   ```

## Next Steps

- [Architecture Overview](architecture/overview) - Understand the system
- [Troubleshooting](troubleshooting) - Common issues
- [Development](development) - Building from source