Settings & Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Settings and Configuration in claude-mem provide a centralized mechanism for managing environment variables, AI provider credentials, system ports, and feature toggles. The system is designed to allow persistent customization of the memory agent's behavior across different AI models and user environments.
The primary source of truth for configuration is a JSON file located at ~/.claude-mem/settings.json. This file is automatically created with default values upon the first run of the application, ensuring a "zero-config" startup experience while allowing for deep customization.
Sources: src/services/worker/http/routes/SettingsRoutes.ts:10, CLAUDE.md:46, README.md:144
Architecture and Data Flow
The configuration system follows a tiered architecture involving the filesystem, a dedicated SettingsManager service, and HTTP route handlers that expose configuration capabilities to the Viewer UI and CLI tools.
Configuration Management Flow
The SettingsRoutes class handles the lifecycle of settings through API endpoints. When a user updates settings via the web interface, the application validates the input against strict schema requirements before committing changes to the filesystem.
The diagram above illustrates the flow of a settings update, emphasizing the validation step and the subsequent cache clearing and service restart required for certain parameters (like network ports) to take effect.
Sources: src/services/worker/http/routes/SettingsRoutes.ts:39-106, src/services/worker-service.ts:503-524
AI Provider Configuration
claude-mem supports multiple AI providers, allowing users to choose the backend that best fits their cost and performance requirements. The system validates provider-specific keys and model strings to prevent runtime failures.
| Provider | Key Settings | Supported Models / Features |
|---|---|---|
| Claude | CLAUDE_MEM_MODEL | Default native provider using Claude Agent SDK |
| Gemini | CLAUDE_MEM_GEMINI_API_KEY | Supports models like gemini-2.5-flash-lite, gemini-3-flash |
| OpenRouter | CLAUDE_MEM_OPENROUTER_API_KEY | Supports custom site URLs and application names |
Users can switch providers dynamically. For instance, the SDKAgent reads the CLAUDE_MEM_MODEL directly from settings to initialize the Claude subprocess for observation generation.
Sources: src/services/worker/http/routes/SettingsRoutes.ts:162-184, src/services/worker/SDKAgent.ts:446-452
Configuration Validation Logic
The system implements strict validation for various setting types to ensure system stability:
- Port Numbers: Must be between 1024 and 65535.
- Python Version: Must follow the
3.Xor3.XXformat (required for Chroma/Vector DB). - Context Counts: Observations count is capped between 1 and 200; Session count between 1 and 50.
- Boolean Strings: Specifically validates "true" or "false" strings for feature toggles.
Sources: src/services/worker/http/routes/SettingsRoutes.ts:160-248
System & Feature Toggles
Beyond AI credentials, the configuration manages the operational environment of the Worker service and the visual density of the context injected into Claude sessions.
Network and Process Settings
- CLAUDE_MEM_WORKER_PORT: The port the Express server listens on (default 37777).
- CLAUDE_MEM_WORKER_HOST: The host binding (e.g.,
127.0.0.1or0.0.0.0). - CLAUDE_MEM_LOG_LEVEL: Controls verbosity (
DEBUG,INFO,WARN,ERROR,SILENT).
Sources: src/services/worker/http/routes/SettingsRoutes.ts:69-95, src/services/worker/README.md:7
Context & Token Economics
The application provides settings to control how much information is displayed and how "savings" are calculated:
- Token Visibility: Toggles for showing read tokens, work tokens, and savings amounts/percentages.
- Observation Filtering: Settings to define which types and concepts of observations are prioritized in context injection.
- Display Configuration: Controls for
FULL_COUNT(0-20) andSESSION_COUNT(1-50) to manage the amount of historical data surfaced.
Sources: src/services/worker/http/routes/SettingsRoutes.ts:96-104, src/services/worker/http/routes/SettingsRoutes.ts:220-234
Branch and MCP Management
The SettingsRoutes also manages meta-configuration related to the software's update channel and the Model Context Protocol (MCP) search server.
MCP Toggling
The MCP search server can be enabled or disabled via an API endpoint. This is implemented by renaming the .mcp.json file to .mcp.json.disabled in the plugin directory, effectively preventing Cursor or Claude from loading the search skill.
Branch Switching
claude-mem supports switching between main and beta branches (e.g., beta/7.0). When a branch switch is requested, the BranchManager performs the git operations, and the SettingsRoutes schedules a worker restart by calling process.exit(0), allowing the process manager (like PM2) to restart the worker on the new branch.
Sources: src/services/worker/http/routes/SettingsRoutes.ts:114-142
Summary of Configuration API
The following endpoints are defined in SettingsRoutes.ts to manage the system state:
| Method | Endpoint | Description |
|---|---|---|
GET | /api/settings | Retrieves current settings from settings.json |
POST | /api/settings | Validates and updates settings; clears port cache |
GET | /api/mcp/status | Checks if the MCP search server is enabled |
POST | /api/mcp/toggle | Toggles the .mcp.json file state |
GET | /api/branch/status | Gets current git branch information |
POST | /api/branch/switch | Switches to a specified allowed branch |
POST | /api/branch/update | Pulls latest updates for the current branch |
Sources: src/services/worker/http/routes/SettingsRoutes.ts:30-46
The configuration system acts as the backbone of claude-mem, ensuring that both the persistent storage and the real-time AI agents operate according to user-defined parameters while maintaining system integrity through strict validation and automated default management.