---
title: "Configuration"
description: "Environment variables and settings for claude-recall"
---
# Configuration
## Settings File
Settings are managed in `~/.claude-recall/settings.json`. The file is auto-created with defaults on first run.
### Core Settings
| Setting | Default | Description |
|-------------------------------|---------------------------------|---------------------------------------|
| `CLAUDE_RECALL_MODEL` | `sonnet` | AI model for processing observations (when using Claude) |
| `CLAUDE_RECALL_PROVIDER` | `claude` | AI provider: `claude`, `gemini`, or `openrouter` |
| `CLAUDE_RECALL_MODE` | `code` | Active mode profile (e.g., `code--es`, `email-investigation`) |
| `CLAUDE_RECALL_CONTEXT_OBSERVATIONS` | `50` | Number of observations to inject |
| `CLAUDE_RECALL_WORKER_PORT` | `37777` | Worker service port |
| `CLAUDE_RECALL_WORKER_HOST` | `127.0.0.1` | Worker service host address |
| `CLAUDE_RECALL_SKIP_TOOLS` | `ListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion` | Comma-separated tools to exclude from observations |
### Gemini Provider Settings
| Setting | Default | Description |
|-------------------------------|---------------------------------|---------------------------------------|
| `CLAUDE_RECALL_GEMINI_API_KEY` | — | Gemini API key ([get free key](https://aistudio.google.com/app/apikey)) |
| `CLAUDE_RECALL_GEMINI_MODEL` | `gemini-2.5-flash-lite` | Gemini model: `gemini-2.5-flash-lite`, `gemini-2.5-flash`, `gemini-3-flash` |
See [Gemini Provider](usage/gemini-provider) for detailed configuration and free tier information.
### OpenRouter Provider Settings
| Setting | Default | Description |
|----------------------------------------------|-----------------------------|---------------------------------------|
| `CLAUDE_RECALL_OPENROUTER_API_KEY` | — | OpenRouter API key ([get key](https://openrouter.ai/keys)) |
| `CLAUDE_RECALL_OPENROUTER_MODEL` | `xiaomi/mimo-v2-flash:free` | Model identifier (supports 100+ models) |
| `CLAUDE_RECALL_OPENROUTER_MAX_CONTEXT_MESSAGES` | `20` | Max messages in conversation history |
| `CLAUDE_RECALL_OPENROUTER_MAX_TOKENS` | `100000` | Token budget safety limit |
| `CLAUDE_RECALL_OPENROUTER_SITE_URL` | — | Optional: URL for analytics |
| `CLAUDE_RECALL_OPENROUTER_APP_NAME` | `claude-recall` | Optional: App name for analytics |
See [OpenRouter Provider](usage/openrouter-provider) for detailed configuration, free model list, and usage guide.
### System Configuration
| Setting | Default | Description |
|-------------------------------|---------------------------------|---------------------------------------|
| `CLAUDE_RECALL_DATA_DIR` | `~/.claude-recall` | Data directory location |
| `CLAUDE_RECALL_LOG_LEVEL` | `INFO` | Log verbosity (DEBUG, INFO, WARN, ERROR, SILENT) |
| `CLAUDE_RECALL_PYTHON_VERSION` | `3.13` | Python version for chroma-mcp |
| `CLAUDE_CODE_PATH` | _(auto-detect)_ | Path to Claude Code CLI (for Windows) |
## Model Configuration
Configure which AI model processes your observations.
### Available Models
Shorthand model names automatically forward to the latest version:
- `haiku` - Fast, cost-efficient
- `sonnet` - Balanced (default)
- `opus` - Most capable
### Using the Interactive Script
```bash
./claude-recall-settings.sh
```
This script manages settings in `~/.claude-recall/settings.json`.
### Manual Configuration
Edit `~/.claude-recall/settings.json`:
```json
{
"CLAUDE_RECALL_MODEL": "sonnet"
}
```
## Mode Configuration
Configure the active workflow mode and language.
### Settings
| Setting | Default | Description |
|---------|---------|-------------|
| `CLAUDE_RECALL_MODE` | `code` | Defines behavior and language. See [Modes & Languages](modes). |
### Examples
**Spanish Code Mode:**
```json
{
"CLAUDE_RECALL_MODE": "code--es"
}
```
**Email Investigation Mode:**
```json
{
"CLAUDE_RECALL_MODE": "email-investigation"
}
```
## Files and Directories
### Data Directory Structure
The data directory location depends on the environment:
- **Production (installed plugin)**: `~/.claude-recall/` (always, regardless of CLAUDE_PLUGIN_ROOT)
- **Development**: Can be overridden with `CLAUDE_RECALL_DATA_DIR`
```
~/.claude-recall/
├── claude-recall.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-extension/
│ └── plugin.json # Plugin metadata
├── .mcp.json # MCP server configuration
├── hooks/
│ └── lifecycle.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
│ ├── engine-runtime.cjs # Worker service (CJS)
│ └── search-server.cjs # MCP search server (CJS)
└── ui/
└── viewer.html # Web viewer UI bundle
```
## Plugin Configuration
### Hooks Configuration
Hooks are configured in `extension/lifecycle/lifecycle.json`:
```json
{
"description": "claude-recall 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
claude-recall 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 worker service port 37777
- **Auto-Invocation**: Claude recognizes natural language queries about past work
## Version Channel
claude-recall supports switching between stable and beta versions via the web viewer UI.
### 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
**Your memory data is preserved** when switching versions. Only the plugin code changes.
<Note>
Endless Mode is experimental and slower than standard mode. See [Beta Features](beta-features) for full details and important limitations.
</Note>
## 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-recall can automatically generate `CLAUDE.md` files in your project folders with activity timelines. This feature is disabled by default.
| Setting | Default | Description |
|---------|---------|-------------|
| `CLAUDE_RECALL_FOLDER_CLAUDEMD_ENABLED` | `false` | Enable auto-generation of folder CLAUDE.md files |
See [Folder Context Files](usage/folder-context) for full documentation on how this feature works, configuration options, and git integration recommendations.
## Context Injection Configuration
claude-recall 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 at http://localhost:37777:
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:
| Setting | Default | Range | Description |
|---------|---------|-------|-------------|
| **Observations** | 50 | 1-200 | Total number of recent observations to include |
| **Sessions** | 10 | 1-50 | Number of recent sessions to pull observations from |
**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**:
| Setting | Default | Options | Description |
|---------|---------|---------|-------------|
| **Count** | 5 | 0-20 | How many observations show expanded details |
| **Field** | narrative | narrative, facts | Which field to expand |
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):
| Setting | Default | Description |
|---------|---------|-------------|
| **Read cost** | true | Show tokens to read each observation |
| **Work investment** | true | Show tokens spent creating the observation |
| **Savings** | true | Show total tokens saved by reusing context |
Token economics help you understand the value of cached observations vs. re-reading files.
### Advanced Settings
| Setting | Default | Description |
|---------|---------|-------------|
| **Model** | sonnet | AI model for generating observations |
| **Worker Port** | 37777 | Port for background worker service |
| **MCP search server** | true | Enable Model Context Protocol search tools |
| **Include last summary** | false | Add previous session's summary to context |
| **Include last message** | false | Add previous session's final message |
### Manual Configuration
Settings are stored in `~/.claude-recall/settings.json`:
```json
{
"CLAUDE_RECALL_CONTEXT_OBSERVATIONS": "100",
"CLAUDE_RECALL_CONTEXT_SESSION_COUNT": "20",
"CLAUDE_RECALL_CONTEXT_OBSERVATION_TYPES": "bugfix,decision,discovery",
"CLAUDE_RECALL_CONTEXT_OBSERVATION_CONCEPTS": "how-it-works,gotcha",
"CLAUDE_RECALL_CONTEXT_FULL_COUNT": "10",
"CLAUDE_RECALL_CONTEXT_FULL_FIELD": "narrative",
"CLAUDE_RECALL_CONTEXT_SHOW_READ_TOKENS": "true",
"CLAUDE_RECALL_CONTEXT_SHOW_WORK_TOKENS": "true",
"CLAUDE_RECALL_CONTEXT_SHOW_SAVINGS_AMOUNT": "true",
"CLAUDE_RECALL_CONTEXT_SHOW_LAST_SUMMARY": "false",
"CLAUDE_RECALL_CONTEXT_SHOW_LAST_MESSAGE": "false"
}
```
**Note**: The Context Settings Modal (at http://localhost:37777) is the recommended way to configure these settings, as it provides live preview of changes.
## Customization
Settings can be customized in `~/.claude-recall/settings.json`.
### Custom Data Directory
Edit `~/.claude-recall/settings.json`:
```json
{
"CLAUDE_RECALL_DATA_DIR": "/custom/path"
}
```
### Custom Worker Port
Edit `~/.claude-recall/settings.json`:
```json
{
"CLAUDE_RECALL_WORKER_PORT": "38000"
}
```
Then restart the worker:
```bash
npm run worker:restart
```
### Custom Model
Edit `~/.claude-recall/settings.json`:
```json
{
"CLAUDE_RECALL_MODEL": "opus"
}
```
Then restart the worker:
```bash
export CLAUDE_RECALL_MODEL=opus
npm run worker:restart
```
### Custom Skip Tools
Control which tools are excluded from observations. Edit `~/.claude-recall/settings.json`:
```json
{
"CLAUDE_RECALL_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
Modify timeouts in `extension/lifecycle/lifecycle.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
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:
```bash
export DEBUG=claude-recall:*
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_RECALL_MODEL
echo $CLAUDE_RECALL_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 `sonnet` and log a warning.
Valid shorthand models (forward to latest version):
- haiku
- sonnet
- opus
### Port Already in Use
If port 37777 is already in use:
1. Set custom port:
```bash
export CLAUDE_RECALL_WORKER_PORT=38000
```
2. Restart worker:
```bash
npm run worker:restart
```
3. Verify new port:
```bash
cat ~/.claude-recall/worker.port
```
## Next Steps
- [Architecture Overview](architecture/overview) - Understand the system
- [Troubleshooting](troubleshooting) - Common issues
- [Development](development) - Building from source
