​

Configuration

​

Settings File

​

Core Settings

​

Gemini Provider Settings

​

OpenRouter Provider Settings

​

System Configuration

​

Model Configuration

​

Available Models

• haiku - Fast, cost-efficient
• sonnet - Balanced (default)
• opus - Most capable

​

Using the Interactive Script

./claude-mem-settings.sh

​

Manual Configuration

{
  "CLAUDE_MEM_MODEL": "sonnet"
}

​

Mode Configuration

​

Settings

​

Examples

{
  "CLAUDE_MEM_MODE": "code--es"
}

{
  "CLAUDE_MEM_MODE": "email-investigation"
}

​

Files and Directories

​

Data Directory Structure

• 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
│   ├── worker-service.cjs  # Worker service (CJS)
│   └── mcp-server.cjs      # MCP search server (CJS)
└── ui/
    └── viewer.html         # Web viewer UI bundle

​

Plugin Configuration

​

Hooks Configuration

{
  "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
      }]
    }]
  }
}

​

Search Configuration (v5.4.0+)

• Skill: plugin/skills/mem-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

​

Version Channel

​

Accessing Version Channel

1. Open the viewer at http://localhost:37777
2. Click the Settings gear icon
3. Find the Version Channel section

​

Switching Versions

• Try Beta: Click “Try Beta (Endless Mode)” to switch to the beta branch with experimental features
• Switch to Stable: Click “Switch to Stable” to return to the production release
• Check for Updates: Pull the latest changes for your current branch

​

Worker Service Management

​

Context Injection Configuration

​

Context Settings Modal

1. Click the gear icon in the header
2. Adjust settings in the right panel
3. See changes reflected live in the Terminal Preview on the left
4. Settings auto-save as you change them

​

Loading Settings

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

​

Filter Settings

• bugfix - Bug fixes and error resolutions
• feature - New functionality additions
• refactor - Code restructuring
• discovery - Learnings about how code works
• decision - Architectural or design decisions
• change - General code changes

• how-it-works - System behavior explanations
• why-it-exists - Rationale for code/design
• what-changed - Change summaries
• problem-solution - Problem/solution pairs
• gotcha - Edge cases and pitfalls
• pattern - Recurring patterns
• trade-off - Design trade-offs

​

Display Settings

​

Advanced Settings

​

Manual Configuration

{
  "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "100",
  "CLAUDE_MEM_CONTEXT_SESSION_COUNT": "20",
  "CLAUDE_MEM_CONTEXT_OBSERVATION_TYPES": "bugfix,decision,discovery",
  "CLAUDE_MEM_CONTEXT_OBSERVATION_CONCEPTS": "how-it-works,gotcha",
  "CLAUDE_MEM_CONTEXT_FULL_COUNT": "10",
  "CLAUDE_MEM_CONTEXT_FULL_FIELD": "narrative",
  "CLAUDE_MEM_CONTEXT_SHOW_READ_TOKENS": "true",
  "CLAUDE_MEM_CONTEXT_SHOW_WORK_TOKENS": "true",
  "CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_AMOUNT": "true",
  "CLAUDE_MEM_CONTEXT_SHOW_LAST_SUMMARY": "false",
  "CLAUDE_MEM_CONTEXT_SHOW_LAST_MESSAGE": "false"
}

​

Customization

​

Custom Data Directory

{
  "CLAUDE_MEM_DATA_DIR": "/custom/path"
}

​

Custom Worker Port

{
  "CLAUDE_MEM_WORKER_PORT": "38000"
}

npm run worker:restart

​

Custom Model

{
  "CLAUDE_MEM_MODEL": "opus"
}

export CLAUDE_MEM_MODEL=opus
npm run worker:restart

​

Custom Skip Tools

{
  "CLAUDE_MEM_SKIP_TOOLS": "ListMcpResourcesTool,SlashCommand,Skill"
}

• ListMcpResourcesTool
• SlashCommand
• Skill
• TodoWrite
• AskUserQuestion

• Include TodoWrite: Remove from skip list to track task planning
• Include AskUserQuestion: Remove to capture decision-making conversations
• Skip additional tools: Add tool names to reduce observation noise

​

Advanced Configuration

​

Hook Timeouts

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

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

​

Worker Memory Limit

​

Logging Verbosity

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

   npm run worker:restart
   
2. Verify environment variables:
   Copy

   echo $CLAUDE_MEM_MODEL
   echo $CLAUDE_MEM_WORKER_PORT
   
3. Check worker logs:
   Copy

   npm run worker:logs
   

​

Invalid Model Name

• haiku
• sonnet
• opus

​

Port Already in Use

1. Set custom port:
   Copy

   export CLAUDE_MEM_WORKER_PORT=38000
   
2. Restart worker:
   Copy

   npm run worker:restart
   
3. Verify new port:
   Copy

   cat ~/.claude-mem/worker.port
   

​

Next Steps

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