Documentation Index

Fetch the complete documentation index at: https://docs.claude-mem.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Configuration

​

Settings File

​

Core Settings

​

Gemini Provider Settings

​

OpenRouter Provider Settings

​

Claude Gateway Settings

​

System Configuration

​

Model Configuration

​

Available Models

​

Picking via the Installer

​

Manual Configuration

{
  "CLAUDE_MEM_MODEL": "claude-haiku-4-5-20251001"
}

​

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        # Version marker written by `npx claude-mem install`/`repair`
├── settings.json           # Worker port + provider/model settings
└── 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
│   ├── version-check.js    # Sub-100ms Setup-hook version marker check
│   ├── 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

• Setup → version-check.js (sub-100ms .install-version check)
• SessionStart → start the worker, then hook claude-code context (context injection)
• UserPromptSubmit → hook claude-code session-init
• PreToolUse (matcher Read) → hook claude-code file-context
• PostToolUse (matcher *) → hook claude-code observation
• Stop → hook claude-code summarize

​

Search Configuration

• MCP Server: 3 tools (search, timeline, get_observations) with progressive disclosure
• HTTP API: 10 endpoints on the worker service port (per-user, default 37700 + (uid % 100); see ~/.claude-mem/settings.json)
• Auto-Invocation: Claude recognizes natural language queries about past work

​

Version Channel

​

Accessing Version Channel

1. Open the viewer at the worker URL (default http://127.0.0.1:<worker-port>; the active port is the value of CLAUDE_MEM_WORKER_PORT in ~/.claude-mem/settings.json)
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

​

Folder Context Files

​

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

• Setup (version-check.js): 300s ceiling but normally < 100ms — only reads .install-version
• SessionStart (worker-start + context): 60s
• UserPromptSubmit: 60s
• PreToolUse (file-context, Read matcher): 60s
• PostToolUse (observation): 120s
• Stop (summary): 120s

​

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:
   npm run worker:restart
   
2. Verify environment variables:
   echo $CLAUDE_MEM_MODEL
   echo $CLAUDE_MEM_WORKER_PORT
   
3. Check worker logs:
   npm run worker:logs
   

​

Invalid Model Name

• claude-haiku-4-5-20251001 (default)
• claude-sonnet-4-6
• claude-opus-4-7

​

Port Already in Use

1. Set custom port:
   export CLAUDE_MEM_WORKER_PORT=38000
   
2. Restart worker:
   npm run worker:restart
   
3. Verify new port:
   curl -s http://127.0.0.1:$CLAUDE_MEM_WORKER_PORT/api/health | jq .port
   

​

Next Steps

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