Setup & Installation

This page covers installing the @verygoodplugins/mcp-automem package and running the guided installer to configure your connection to the AutoMem service. For information about deploying the AutoMem backend service itself, see Prerequisites. For detailed configuration options and environment variable resolution, see Configuration Tools.

Prerequisites

The mcp-automem package is a bridge component that translates Model Context Protocol (MCP) calls into AutoMem HTTP API requests. It does not store memories itself — it requires a separate AutoMem backend service that handles memory storage, retrieval, and graph operations.

Node.js Runtime Requirements

The mcp-automem package requires Node.js 20.19.0+, 22.13.0+, or 24+. This version requirement is enforced in the package manifest (engines: "^20.19.0 || ^22.13.0 || >=24") and necessary for:

ECMAScript modules (ESM) support used throughout the codebase
Native fetch API used by the HTTP client
Modern async/await patterns in the MCP SDK

Verify your Node.js version:

node --version
# Should output: v20.19.x, v22.13.x, or v24.x.x or higher

Install or upgrade Node.js:

Method	Command
nvm (recommended)	`nvm install 20`
Official Installer	Download from nodejs.org
Homebrew (macOS)	`brew install node@20`
Package Manager (Linux)	`apt install nodejs` or equivalent

AutoMem Service Requirement

The MCP server cannot function without a running AutoMem service. You must choose one deployment option before installing:

Why separate services?

Deployment flexibility: Run memory backend on different infrastructure than MCP client
Multi-client support: Multiple MCP servers can share one AutoMem instance
Scaling independence: Scale memory storage separately from MCP protocol handling
Technology separation: Backend uses Python/Flask while client uses TypeScript

Option 1: Local Development

Best for: development, testing, single-machine use, privacy-focused setups.

Requirements: Docker and Docker Compose installed, Git, 2GB RAM, ports 8001, 6379, 3000, 6333 available.

git clone https://github.com/verygoodplugins/automem
cd automem
make dev

This launches: Flask service on :8001, FalkorDB on :6379, Qdrant on :6333, FalkorDB graph browser on :3000.

Endpoint configuration: AUTOMEM_API_URL=http://127.0.0.1:8001 (no API key required in development mode)

Option 2: InstaPods Hosted

Best for: fastest hosted setup, individual production use, generated MCP configuration.

Open the AutoMem app on InstaPods
Deploy the AutoMem pod
Copy the generated MCP config
Note the HTTPS endpoint and API token

Endpoint configuration: AUTOMEM_API_URL=https://your-instapods-url (base URL, no /health path), AUTOMEM_API_KEY=<generated-token>

Typical cost: $15/mo flat for the AutoMem plan.

Option 3: Railway Cloud

Best for: production use, multi-device access, team collaboration, always-on availability.

Click Railway deploy button (see AutoMem service repository)
Connect GitHub account
Configure environment variables in Railway dashboard
Note the generated Railway URL: https://your-project.up.railway.app

Endpoint configuration: AUTOMEM_API_URL=https://your-project.up.railway.app, AUTOMEM_API_KEY=<generated-token>

Typical costs: development ~$0.50-1.00/month, production ~$5-10/month.

Option 4: Self-Hosted Production

Best for: enterprise deployments, custom infrastructure, air-gapped environments.

Platform	Setup Complexity
Docker Compose	Medium
Kubernetes	High
VPS (DigitalOcean, Linode)	Medium
AWS/GCP/Azure	High

Network Connectivity Requirements

Deployment	Ports Used	Accessibility
Local	`8001` (AutoMem API); the Compose stack also publishes `6379`, `3000`, `6333`, and `6334` (FalkorDB and Qdrant)	Published on all host interfaces by default (Docker Compose port mapping); see Restricting Network Exposure
InstaPods	`443` (HTTPS)	Internet
Railway	`443` (HTTPS)	Internet
Self-hosted	`8001` or custom	Depends on configuration

Platform-Specific Config Paths

Before installation, determine where these files will be located:

File	Purpose	Typical Location	Required When
`.env`	AutoMem endpoint and API key	Current directory or home	Setup wizard
`claude_desktop_config.json`	Claude Desktop MCP config	OS-specific config directory	Claude Desktop
`~/.cursor/mcp.json`	Cursor MCP server config	User home directory	Cursor IDE
`~/.claude.json`	Claude Code MCP config	User home directory	Claude Code
`~/.codex/config.toml`	Codex MCP config	User home directory	OpenAI Codex

Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Cursor IDE:

All platforms: ~/.cursor/mcp.json (MCP server config)
Project-specific: .cursor/rules/automem.mdc (memory rules)

Claude Code:

All platforms: ~/.claude.json (MCP server config)
All platforms: ~/.claude/settings.json (permissions)
All platforms: ~/.claude/CLAUDE.md (memory rules)

Pre-Installation Checklist

System Requirements

Node.js 20.19.0+, 22.13.0+, or 24+ installed (node --version)
npm available (npm --version)
Terminal access with write permissions

AutoMem Service

AutoMem service deployed (local, InstaPods, Railway, or self-hosted)
Service is running and accessible
Health endpoint responds: curl http://your-endpoint/health
Note your AUTOMEM_API_URL (the base URL of your AutoMem service)
Note your AUTOMEM_API_KEY (if using authentication)

Network Connectivity

MCP client can reach AutoMem service (test with curl)
No firewall blocking the connection
HTTPS certificate valid (if using Railway or self-hosted with SSL)

File System Access

Write permission to create .env file
Access to platform-specific config directories
Ability to restart AI platform applications

Installation Methods

The mcp-automem package can be installed three ways, depending on your use case.

Installation Entry Points

graph TB
    subgraph "Package Entry Points"
        PKG[package.json]
        BIN["bin: { mcp-automem: dist/index.js }"]
        MAIN["main: dist/index.js"]
    end

    subgraph "Installation Methods"
        NPX["npx @verygoodplugins/mcp-automem"]
        GLOBAL["npm install -g"]
        LOCAL["git clone + npm install"]
    end

    subgraph "Execution Modes"
        CLI["CLI Mode<br/>(with args)"]
        SERVER["Server Mode<br/>(no args)"]
    end

    subgraph "Runtime"
        INDEX["src/index.ts"]
        SETUP["src/cli/setup.ts"]
        MCP["MCP Server<br/>(stdio transport)"]
    end

    PKG --> BIN
    PKG --> MAIN

    NPX --> BIN
    GLOBAL --> BIN
    LOCAL --> INDEX

    BIN --> INDEX

    INDEX --> CLI
    INDEX --> SERVER

    CLI --> SETUP
    SERVER --> MCP

Dual mode detection: The entry point at src/index.ts determines whether to run as an MCP server (no arguments) or execute a CLI command (with arguments). This allows the same package to function as both an MCP server process and a CLI tool.

Method 1: NPX (Recommended)

The recommended installation method uses npx to run the package without installing it globally. This ensures you always use the latest version and avoids version conflicts.

npx @verygoodplugins/mcp-automem install

How it works:

npx downloads the package temporarily to execute it
No global installation required
Automatically uses the latest published version
Suitable for CI/CD pipelines and one-off commands

When to use: For platform configurations (Claude Desktop, Cursor, Claude Code) where the MCP server is launched on-demand via npx in the config file.

Method 2: Global Installation

Install the package globally to use the mcp-automem command without npx.

npm install -g @verygoodplugins/mcp-automem
mcp-automem install

When to use: If you run CLI commands frequently or want faster execution without npx download delays.

Method 3: Local Development

For contributors or those customizing the codebase, clone and build locally.

git clone https://github.com/verygoodplugins/mcp-automem
cd mcp-automem
npm install
npm run build
node dist/index.js install

The built server is available at dist/index.js.

Build process:

npm run prebuild — Regenerates the memory-policy artifacts first, then syncs template versions (audited against mcp-automem 0.18.0 at 0990a43a)
npm run build — Compiles TypeScript from src/ to dist/
npm run postbuild — Builds the OpenClaw plugin package (node scripts/build-openclaw-plugin-package.mjs; the script sets the executable bit on dist/index.js via Node, not a shell chmod)
npm run dev — Runs the TypeScript source directly via tsx watch src/index.ts for development

Guided installer

install is the guided installer. It asks where AutoMem runs, verifies the endpoint, writes .env, and configures the agents you select. Pass --dry-run to preview and --yes to apply without prompts. Host commands such as claude-code and cursor remain scriptable writers for one platform.

setup is an alias of install as of 0.17.0. The older setup flags (--env, --claude-code, --claude-dir, --claude-dry-run) are no longer accepted; they error with a pointer to install, config, or the relevant host writer.

The installer writes .env in the current directory after it verifies the endpoint:

AUTOMEM_API_URL=http://localhost:8001
AUTOMEM_API_KEY=your-api-key-here

Dotenv loads that file when the MCP server starts. System environment variables override it (see Configuration Tools).

Config Output

Print the current configuration for other platforms (Claude Desktop JSON, Claude Code env export, Hermes YAML):

npx @verygoodplugins/mcp-automem config

Use config when you want the CLI to reprint your current configuration later. This command prints human-readable output for the supported surfaces, including Claude Desktop JSON, Claude Code env export lines with the your-auto-mem-api-key placeholder, and the Hermes mcp_servers YAML snippet. For Hermes provider mode, run npx @verygoodplugins/mcp-automem hermes.

If you need machine-readable output instead, add --format=json (or --json):

npx @verygoodplugins/mcp-automem config --format=json

That JSON mode emits the raw MCP configuration object. It is useful for scripting. The default text output is the human-readable snippets.

Post-Installation File Structure

After the guided installer writes .env, your directory contains:

your-project/
├── .env                          # Written by the guided installer
│   ├── AUTOMEM_API_URL=...
│   └── AUTOMEM_API_KEY=...
└── node_modules/                 # If npm install was run
    └── @verygoodplugins/
        └── mcp-automem/
            ├── dist/
            │   └── index.js      # MCP server entry point
            ├── templates/        # Platform-specific rules
            │   ├── claude-code/
            │   ├── antigravity/
            │   ├── codex/
            │   ├── copilot/
            │   ├── cursor/
            │   ├── grok/
            │   ├── hermes/
            │   └── openclaw/
            └── package.json

Templates: In the audited mcp-automem 0.18.0 release (0990a43a90186fd07c5fe521af85fe843ad1cfa5), the published templates/ package surface includes antigravity, claude-code, codex, copilot, cursor, grok, hermes, and openclaw. See Platform Installers for how each template is used.

Verification

After installation, verify the setup works by checking the database health:

curl http://your-endpoint/health

Expected health response:

{
  "status": "healthy",
  "falkordb": "connected",
  "qdrant": "connected",
  "memory_count": 0,
  "enrichment": {
    "status": "running",
    "queue_depth": 0
  }
}

For platform-specific verification (Claude Desktop, Cursor, etc.), see the respective integration guides in Platform Installers.

Common Installation Issues

Issue	Cause	Solution
`AUTOMEM_API_URL not set`	No endpoint is configured in the environment or in a `.env` file in the current directory. The client falls back to `http://127.0.0.1:8001` and prints this warning only in an interactive terminal	Run the `install` wizard (`setup` is an alias), or set `AUTOMEM_API_URL`. Nothing to fix if your AutoMem runs at the default local address
`Connection refused`	AutoMem service not running	Start service: `cd automem && make dev`
`401 Unauthorized`	Invalid API key	Check `AUTOMEM_API_KEY` matches service token
`npx: command not found`	Node.js not installed	Install Node.js 20.19.0+, 22.13.0+, or 24+
`Module not found` errors	Incomplete installation	Run `npm install` or use `npx` instead

Debug mode: Set AUTOMEM_LOG_LEVEL=debug to enable verbose logging:

AUTOMEM_LOG_LEVEL=debug npx @verygoodplugins/mcp-automem

Issue: Node.js Version Too Old

Symptom: Error during installation: The engine "node" is incompatible with this module

Solution: Upgrade Node.js to version 20.19+, 22.13+, or 24+ using nvm or official installer.

Issue: AutoMem Service Not Running

Symptom: MCP server logs show ECONNREFUSED or Service unreachable

Solution:

Verify service is running: curl http://your-endpoint/health
Check Docker containers for local: docker ps | grep automem
Check Railway logs for cloud deployments

Issue: Network Connectivity

Symptom: Timeouts when calling AutoMem API

Solution:

Verify endpoint URL is correct (no typos)
Check firewall rules if self-hosted
Ensure AutoMem service is bound to correct interface (not just localhost)
Test with curl from same machine as MCP client

Issue: Port Conflicts

Symptom: Local AutoMem service fails to start on port 8001

Solution:

Check what’s using the port: lsof -i :8001 (macOS/Linux) or netstat -ano | findstr :8001 (Windows)
Stop conflicting service or reconfigure AutoMem to use different port
Update AUTOMEM_API_URL accordingly

Next Steps

After completing installation:

Configure environment variables — See Configuration Tools for advanced options like custom endpoints and authentication
Set up platform integration — See Platform Installers for Claude Desktop, Cursor, Claude Code, etc.
Store your first memory — Use the store_memory MCP tool in your AI platform of choice