Configuration

Settings File

Settings are managed in ~/.claude-mem/settings.json. The file is auto-created with defaults on first run.

Core Settings

Gemini Provider Settings

See Gemini Provider for detailed configuration and free tier information.

OpenRouter Provider Settings

See OpenRouter Provider for detailed configuration, free model list, and usage guide.

Claude Gateway Settings

Gateway credentials live in ~/.claude-mem/.env, not settings.json.

Use LiteLLM Gateway when you want CLAUDE_MEM_PROVIDER=claude to route through LiteLLM while preserving the Claude Agent SDK worker path.

System Configuration

Model Configuration

Configure which Claude model compresses your observations (only applies when CLAUDE_MEM_PROVIDER=claude).

Available Models

Picking via the Installer

npx claude-mem install prompts for the Claude model (when the Claude provider is selected) and persists the choice to ~/.claude-mem/settings.json.

Manual Configuration

Edit ~/.claude-mem/settings.json:

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

Mode Configuration

Configure the active workflow mode and language.

Settings

Examples

Spanish Code Mode:

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

Email Investigation Mode:

{
  "CLAUDE_MEM_MODE": "email-investigation"
}

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        # 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

Hooks are registered in plugin/hooks/hooks.json. The current shape uses a single dispatcher (worker-service.cjs hook claude-code <event>) launched through bun-runner.js, plus a fast Setup-phase version-check.js. The events wired up are:

• 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

The exact hooks.json entries are written by the installer; do not hand-edit them in the marketplace copy unless you know what you're doing.

Search Configuration

Claude-Mem provides MCP search tools for querying your project history.

No configuration required - MCP tools are automatically available in Claude Code sessions.

Search operations are provided via:

• 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

Claude-Mem supports switching between stable and beta versions via the web viewer UI.

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

Your memory data is preserved when switching versions. Only the plugin code changes.

Worker Service Management

Worker service is managed by Bun as a background process. The worker auto-starts on first session and runs continuously in the background.

Folder Context Files

Claude-mem can automatically generate CLAUDE.md files in your project folders with activity timelines. This feature is disabled by default.

See Folder Context Files for full documentation on how this feature works, configuration options, and git integration recommendations.

Context Injection Configuration

Claude-Mem injects past observations into each new session, giving Claude awareness of recent work. You can configure exactly what gets injected using the Context Settings Modal.

Context Settings Modal

Access the settings modal from the web viewer (the worker prints its URL on startup; default is http://127.0.0.1:<worker-port>):

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

The Terminal Preview shows exactly what will be injected at the start of your next Claude Code session for the selected project.

Loading Settings

Control how many observations are injected:

Considerations:

• 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

Control which observation types and concepts are included:

Types (select any combination):

• 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

Concepts (select any combination):

• 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

Use "All" or "None" buttons to quickly select/deselect all options.

Display Settings

Control how observations appear in the context:

Full Observations:

The most recent N observations (set by Count) show their full narrative or facts. Remaining observations show only title, type, and token counts in a compact table format.

Token Economics (toggles):

Token economics help you understand the value of cached observations vs. re-reading files.

Advanced Settings

Manual Configuration

Settings are stored in ~/.claude-mem/settings.json:

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

Note: The Context Settings Modal (in the web viewer) is the recommended way to configure these settings, as it provides live preview of changes.

Customization

Settings can be customized in ~/.claude-mem/settings.json.

Custom Data Directory

Edit ~/.claude-mem/settings.json:

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

Custom Worker Port

Edit ~/.claude-mem/settings.json:

{
  "CLAUDE_MEM_WORKER_PORT": "38000"
}

Then restart the worker:

npm run worker:restart

Custom Model

Edit ~/.claude-mem/settings.json:

{
  "CLAUDE_MEM_MODEL": "opus"
}

Then restart the worker:

export CLAUDE_MEM_MODEL=opus
npm run worker:restart

Custom Skip Tools

Control which tools are excluded from observations. Edit ~/.claude-mem/settings.json:

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

Default excluded tools:

• ListMcpResourcesTool
• SlashCommand
• Skill
• TodoWrite
• AskUserQuestion

Common customizations:

• 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

Changes take effect on the next tool execution (no worker restart needed).

Advanced Configuration

Hook Timeouts

Hook timeouts are written into plugin/hooks/hooks.json by the installer. The current defaults match the shape of the workload at each lifecycle stage:

• 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

The Setup hook never installs anything — runtime install (Bun, uv, bun install) happens in npx claude-mem install / npx claude-mem repair outside the session lifecycle.

Worker Memory Limit

The worker service is managed by Bun and will automatically restart if it encounters issues. Memory usage is typically low (~100-200MB).

Logging Verbosity

Enable debug logging:

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:

   bashCopy

   npm run worker:restart
   

2. Verify environment variables:

   bashCopy

   echo $CLAUDE_MEM_MODEL
   echo $CLAUDE_MEM_WORKER_PORT
   

3. Check worker logs:

   bashCopy

   npm run worker:logs
   

Invalid Model Name

If you specify an invalid Claude model name, the worker logs a warning and uses the default. Valid Claude models for CLAUDE_MEM_MODEL:

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

Port Already in Use

The default worker port is 37700 + (uid % 100), so different OS users on the same machine get different ports automatically. If you still hit a collision (e.g. running multiple profiles as the same UID), set a fixed port:

1. Set custom port:

   bashCopy

   export CLAUDE_MEM_WORKER_PORT=38000
   

2. Restart worker:

   bashCopy

   npm run worker:restart
   

3. Verify new port:

   bashCopy

   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