Configuration Tools

This page explains how to configure the mcp-automem client to connect to your AutoMem service. It covers environment variables, configuration resolution priority, platform-specific configuration files, and validation. For initial setup instructions, see Setup & Installation. For platform-specific integration details, see Platform Installers.

The examples on this page are pinned to the audited mcp-automem 0.16.0 release commit 9a0bbf754dd31db524da25638b0e97907e32ff37.

Environment Variables

The mcp-automem client uses two primary environment variables to locate and authenticate with the AutoMem backend service. These can be set via .env file, shell environment, or platform-specific MCP configuration files.

Variable	Required	Default	Description
`AUTOMEM_API_URL`	Yes	`http://127.0.0.1:8001`	HTTP URL of the AutoMem service
`AUTOMEM_API_KEY`	No	(none)	API key for authenticated instances
`AUTOMEM_API_TOKEN`	No	(none)	Alternative name for API key
`AUTOMEM_PROCESS_TAG`	No	(none)	Process title tag for safe cleanup
`MCP_PROCESS_TAG`	No	(none)	Alternative process tag variable
`AUTOMEM_LOG_LEVEL`	No	(none)	Set to `debug` for verbose logging
`AUTOMEM_RECALL_TOKEN_BUDGET`	No	`18000`	Estimated token budget for MCP `recall_memory` responses

AUTOMEM_API_URL

Specifies the HTTP endpoint of your AutoMem service. Common values:

Local development: http://127.0.0.1:8001 or http://localhost:8001
Railway deployment: https://your-service.railway.app
Custom deployment: Your service’s public or internal URL

The endpoint is read at server startup by AutoMemClient and written by the setup wizard. The legacy alias AUTOMEM_ENDPOINT is also accepted.

AUTOMEM_API_KEY

Optional authentication token for secured AutoMem instances. Required when deploying to Railway or other hosted environments. The client checks several sources for compatibility, including the Claude Code plugin’s option-passing convention:

AUTOMEM_API_KEY (preferred)
AUTOMEM_API_TOKEN (alternative)
CLAUDE_PLUGIN_OPTION_API_KEY / CLAUDE_PLUGIN_OPTION_api_key (Claude Code plugin option)
CLAUDE_PLUGIN_OPTION_API_TOKEN / CLAUDE_PLUGIN_OPTION_api_token (Claude Code plugin option)

The readAutoMemApiKeyFromEnv() function checks these in priority order and returns the first truthy, trimmed value:

AUTOMEM_API_KEY
AUTOMEM_API_TOKEN
CLAUDE_PLUGIN_OPTION_API_KEY or CLAUDE_PLUGIN_OPTION_api_key
CLAUDE_PLUGIN_OPTION_API_TOKEN or CLAUDE_PLUGIN_OPTION_api_token

Process Tags

Optional variables for multi-process environments. When set, the server updates process.title to enable safe process management by supervisors like AutoHub:

AUTOMEM_PROCESS_TAG=cursor-session-1 npx @verygoodplugins/mcp-automem

Configuration Resolution Priority

The client resolves configuration from multiple sources with a defined priority order. This allows flexible deployment while maintaining sensible defaults.

Environment Variable Resolution Flow

graph TB
    subgraph Env_Resolution["Environment Variable Resolution<br/>src/env.ts + src/index.ts"]
        DOTENV["dotenv.config()<br/>.env file loading"]

        ENDPOINT_CHECK{"AUTOMEM_API_URL<br/>nonblank?"}
        PLUGIN_URL_CHECK{"CLAUDE_PLUGIN_OPTION_API_URL<br/>nonblank?"}
        LEGACY_URL_CHECK{"AUTOMEM_ENDPOINT<br/>nonblank?"}
        ENDPOINT_DEFAULT["Default:<br/>http://127.0.0.1:8001"]
        ENDPOINT_VALUE["Use AUTOMEM_API_URL"]
        PLUGIN_URL_VALUE["Use Claude plugin URL"]
        LEGACY_URL_VALUE["Use legacy alias"]

        API_KEY_FUNC["readAutoMemApiKeyFromEnv()<br/>src/env.ts"]
        KEY_PRIORITY["Priority:<br/>1. AUTOMEM_API_KEY<br/>2. AUTOMEM_API_TOKEN<br/>3. CLAUDE_PLUGIN_OPTION_API_KEY / api_key<br/>4. CLAUDE_PLUGIN_OPTION_API_TOKEN / api_token"]
    end

    subgraph Client_Config["AutoMemClient Config<br/>src/index.ts"]
        CONFIG_OBJ["clientConfig: AutoMemConfig<br/>{ endpoint, apiKey }"]
        CLIENT_INSTANCE["new AutoMemClient(config)"]
    end

    DOTENV --> ENDPOINT_CHECK
    ENDPOINT_CHECK -->|"No"| PLUGIN_URL_CHECK
    ENDPOINT_CHECK -->|"Yes"| ENDPOINT_VALUE
    PLUGIN_URL_CHECK -->|"No"| LEGACY_URL_CHECK
    PLUGIN_URL_CHECK -->|"Yes"| PLUGIN_URL_VALUE
    LEGACY_URL_CHECK -->|"No"| ENDPOINT_DEFAULT
    LEGACY_URL_CHECK -->|"Yes"| LEGACY_URL_VALUE
    ENDPOINT_DEFAULT --> CONFIG_OBJ
    ENDPOINT_VALUE --> CONFIG_OBJ
    PLUGIN_URL_VALUE --> CONFIG_OBJ
    LEGACY_URL_VALUE --> CONFIG_OBJ

    DOTENV --> API_KEY_FUNC
    API_KEY_FUNC --> KEY_PRIORITY
    KEY_PRIORITY --> CONFIG_OBJ

    CONFIG_OBJ --> CLIENT_INSTANCE

CLI Configuration File Locations

graph TB
    subgraph "Queue CLI Resolution Priority"
        direction TB
        ENV["1. Environment variables<br/>AUTOMEM_API_URL / AUTOMEM_ENDPOINT<br/>+ API key (.env or shell)"]
        CLAUDE_JSON["2. ~/.claude.json<br/>scans mcpServers entries"]
        DEFAULT["3. Default<br/>http://127.0.0.1:8001"]
    end

    RESOLVE["resolveAutoMemConfig()<br/>src/cli/queue.ts"] --> ENV
    ENV -->|Not found| CLAUDE_JSON
    CLAUDE_JSON -->|Not found| DEFAULT

Priority Levels

Environment variables (highest priority)
- Direct shell environment: export AUTOMEM_API_URL=...
- .env file in current directory (loaded via dotenv)
- Platform-specific MCP server env blocks
- For MCP server startup, endpoint resolution is AUTOMEM_API_URL → CLAUDE_PLUGIN_OPTION_API_URL → AUTOMEM_ENDPOINT → default
~/.claude.json configuration
- Used by CLI commands when environment is not set
- Fallback for queue processing and other utilities
- Scans all mcpServers entries for AutoMem config
Default values (lowest priority)
- endpoint: http://127.0.0.1:8001
- apiKey: undefined

The queue CLI uses resolveAutoMemConfig() in src/cli/queue.ts, which checks AUTOMEM_API_URL, then the deprecated AUTOMEM_ENDPOINT, then ~/.claude.json, then the default. The Claude plugin URL tier shown in the diagram above applies to MCP server startup, not queue CLI fallback.

Platform-Specific Configuration Files

Each AI platform stores MCP server configuration differently. The setup wizard and CLI tools generate appropriate configuration for each platform.

Configuration File Locations

Platform	Configuration File	Format
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\claude_desktop_config.json` (Windows) / `~/.config/Claude/claude_desktop_config.json` (Linux)	JSON
Cursor IDE	`~/.cursor/mcp.json`	JSON
Claude Code	`~/.claude.json`	JSON
Codex	`~/.codex/config.toml`	TOML
OpenClaw	`~/.openclaw/openclaw.json`	JSON

JSON Configuration Example (Claude Desktop, Cursor, Claude Code)

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["@verygoodplugins/mcp-automem"],
      "env": {
        "AUTOMEM_API_URL": "http://localhost:8001",
        "AUTOMEM_API_KEY": "your-api-key"
      }
    }
  }
}

This generic JSON example matches the shipped config --format=json output shape: it uses the memory server key and does not prepend -y in args. The command and args launch the MCP server in stdio mode, and the env block passes configuration to the server process.

TOML Configuration Example (Codex)

[mcp_servers.memory]
command = "npx"
args = ["-y", "@verygoodplugins/mcp-automem"]

[mcp_servers.memory.env]
AUTOMEM_API_URL = "http://localhost:8001"
AUTOMEM_API_KEY = "your-api-key"

This example mirrors the shipped Codex template. It documents the released config shape, but whether a specific Codex build accepts and renders it is still a UI-level check in the host app.

Configuration Validation

The client performs validation at multiple stages to ensure reliable operation and provide clear error messages.

Validation Flow

The setup command collects and saves your configuration:

Prompt for API URL: Prompts for AUTOMEM_API_URL with default http://127.0.0.1:8001
Prompt for API key: Optionally prompts for AUTOMEM_API_KEY (skipped if TTY unavailable)
Confirmation prompt: Asks "Write settings to <path>?" before persisting
Configuration write: Saves AUTOMEM_API_URL and AUTOMEM_API_KEY to .env

Runtime Validation

When the MCP server starts, it performs startup validation:

Loads .env file (if present) via dotenv.config()
Reads AUTOMEM_API_URL (or legacy AUTOMEM_ENDPOINT) from environment
Reads API key from environment (checking all supported variable names)
Creates AutoMemClient instance with resolved config
Logs connection details to stderr (never stdout, to avoid polluting JSON-RPC stream)

Content Size Governance

The store_memory tool enforces content size limits to maintain embedding quality:

Limit Type	Threshold	Behavior
Soft limit	500 characters	Warning; backend may auto-summarize
Hard limit	2000 characters	Rejected immediately with error

Special Configuration Options

Stdio Server Mode Configuration

When launched without arguments, the package runs in MCP server mode using stdio transport:

# Server mode (no args) - used by platform config files
npx @verygoodplugins/mcp-automem

In server mode, all logging is redirected to stderr to prevent contaminating the JSON-RPC stdio stream. The dotenv library is configured with quiet: true to suppress its output.

CLI Mode Configuration

When launched with a command (e.g., setup, config, recall), the package runs in CLI mode. Configuration is resolved using the priority system described above.

Example CLI commands that require configuration:

recall — Direct query tool
queue — Queue processing
config — Configuration snippet generation

# All CLI commands use the same config resolution
npx @verygoodplugins/mcp-automem recall --query "project architecture"
npx @verygoodplugins/mcp-automem queue
npx @verygoodplugins/mcp-automem config

Debug Logging

Set AUTOMEM_LOG_LEVEL=debug to enable verbose logging in server mode:

AUTOMEM_LOG_LEVEL=debug npx @verygoodplugins/mcp-automem

At the audited release, debug stderr is narrow:

AUTOMEM_PROCESS_TAG or MCP_PROCESS_TAG can add a tagged process-title line in interactive sessions.
Server mode logs AutoMem MCP server running.

Configuration Generation

The CLI provides tools to generate platform-specific configuration snippets without modifying files.

Config Command

# Generate JSON snippet (Claude Desktop, Cursor, Claude Code)
npx @verygoodplugins/mcp-automem config

Outputs configuration for the current environment in JSON format. Uses the same resolution priority as the runtime system.

Platform Installers

Each platform installer generates and installs appropriate configuration:

Command	Generated Files	Configuration Location
`cursor`	`.cursor/rules/automem.mdc`	`~/.cursor/mcp.json` (manual)
`claude-code`	Hook scripts in `~/.claude/hooks/`, support scripts in `~/.claude/scripts/`	Merges `~/.claude/settings.json` (CLAUDE.md must be appended manually)
`codex`	`AGENTS.md` updates	`~/.codex/config.toml` (manual)
`openclaw`	`<workspace>/skills/automem/SKILL.md` + `<workspace>/config/mcporter.json` (MCP mode) or `plugins.entries.automem` (plugin mode)	`~/.openclaw/openclaw.json` (automatic)

See Platform Installers for detailed instructions per platform.

Troubleshooting Configuration Issues

Connection Failures

If the MCP server cannot reach the AutoMem service:

Verify endpoint: Check that AUTOMEM_API_URL is correct and reachable
Test health endpoint: Run curl http://your-endpoint/health
Check API key: Ensure AUTOMEM_API_KEY matches your deployed service
Network issues: Verify firewall rules and DNS resolution

Configuration Not Found

If the server cannot find configuration:

Environment variables: Ensure .env is in the working directory or variables are exported
Platform config: Check that platform config files exist and are readable
Resolution priority: Remember environment variables override platform configs

Service Unavailable

The queue command skips processing if the endpoint is unreachable — this prevents queue operations from blocking when the service is down.

$ npx @verygoodplugins/mcp-automem queue
AutoMem endpoint http://localhost:8001 is not reachable
Skipping queue processing. Start the AutoMem service and retry.

API Key Mismatch

If you receive 401 Unauthorized errors:

Check what token is configured: grep AUTOMEM_API_KEY .env
Compare against the token in your AutoMem service configuration
For Railway: check the AUTOMEM_API_TOKEN variable in the Railway dashboard
Update .env or platform config with the correct token

Multiple Configurations Conflict

If configuration behaves unexpectedly, use debug mode to see which values are being loaded:

AUTOMEM_LOG_LEVEL=debug npx @verygoodplugins/mcp-automem

Expect the narrow stderr lines above rather than per-tool traces, HTTP dumps, or retry/backoff logs.