Installation Guide

Complete setup instructions for AutoMem MCP across all platforms.

Prerequisites

You need a running AutoMem service instance. Quick options:

Local development (fastest): Run make dev - see AutoMem Installation Guide
Railway cloud (recommended): One-click deploy - see AutoMem Railway Guide
Self-hosted: Docker/production - see AutoMem Deployment Options

Quick Start

Guided install (fastest)

One command walks you through everything — where AutoMem runs, endpoint verification, writing .env, and configuring each agent:

npx @verygoodplugins/mcp-automem install

It asks where AutoMem should run (Hosted Cloud, Local Docker, or an Existing Endpoint). For Hosted Cloud you pick a provider:

InstaPods — opens the InstaPods setup page in your browser. It deploys AutoMem (Grow plan) and emails you your API URL + key; you paste them back into the installer. Already have them? Skip the browser and paste directly.
Railway — if the railway CLI isn't on your PATH, the installer offers to install it for you with npm i -g @railway/cli (with your confirmation — you already have Node from running this installer). It then signs you in via the CLI (a browser hand-off that also creates an account if you're new) and deploys the AutoMem template straight from the terminal — no browser tab for the deploy itself — reading back the service domain + API token automatically. If you decline the CLI install, or the terminal deploy can't complete, it falls back to the template's Deploy Now page in your browser, then captures the credentials (via railway link, or by paste).
Other — already deployed AutoMem somewhere? Paste your endpoint + token and the installer takes it from there.

It then verifies the endpoint (/health + an authenticated recall probe when you supply a key), then offers to configure your agents (Codex, Claude Code, Cursor, OpenClaw, Hermes). For Claude Code it offers the plugin (recommended — bundles the MCP server + hooks and auto-updates) or a settings-level install. When the claude CLI is on your PATH, the installer runs claude plugin install for you and passes the verified endpoint as plugin config; API keys are not passed in process arguments, so configure the key through Claude Code's plugin UI or AUTOMEM_API_KEY. If claude is unavailable, it prints the two /plugin commands to run inside Claude Code. Every change is shown in a review plan before anything is written, and each modified file keeps a <file>.bak backup.

Non-interactive / scriptable use:

# Preview the plan without writing anything
npx @verygoodplugins/mcp-automem install --dry-run --target existing \
  --endpoint https://your-automem.example --api-key "$AUTOMEM_API_KEY"

# Apply without prompts (CI / dotfiles)
npx @verygoodplugins/mcp-automem install --yes --target existing \
  --endpoint https://your-automem.example --clients codex,cursor \
  --claude-code-mode settings

Flags: --target <local|cloud|existing>, --cloud-provider <instapods|railway|other>, --clients <list>, --endpoint, --api-key, --local-dir, --claude-code-mode <plugin|settings>, --hermes-mode <mcp|provider|both>, --dry-run, --yes, --no-agent-install. The same values can be passed as AUTOMEM_* environment variables. For CI/dotfiles, prefer --target existing with --endpoint and --api-key; InstaPods is an interactive browser+paste flow. Railway can run non-interactively only when the railway CLI is already installed and either signed in or authenticated with RAILWAY_API_TOKEN, and --yes --cloud-provider railway is supplied. --dry-run never opens a browser, installs or runs the railway CLI, deploys, or charges anything — it only prints the plan.

Without a TTY and without --yes/--dry-run, install prints the review plan and stops without writing — re-run with --yes to apply.

API keys are paired with their endpoint. A key belongs to the AutoMem instance it was issued for, so the installers never carry one to a different host. If you re-run against a new --endpoint without passing --api-key, any key inherited from your shell (AUTOMEM_API_KEY / AUTOMEM_API_TOKEN) or from the agent's existing config is dropped rather than reused, and a key already persisted in the project .env is removed — the MCP server loads that file at startup, so leaving it would send the old credential to the new host. Pass --api-key to set the credential for the new endpoint. A key exported with no endpoint alongside it is not bound to anything and is still used; a re-run at the same endpoint keeps the key it already has.

Removing AutoMem: uninstall is per-agent — npx @verygoodplugins/mcp-automem uninstall <cursor|claude-code|codex|hermes|grok> (add --clean-all to also drop the MCP server config). OpenClaw owns its own plugin lifecycle, so remove the AutoMem plugin from OpenClaw directly with openclaw plugins uninstall automem rather than the uninstall command above.

Manual setup

Prefer to do it by hand? Follow these two steps:

Set up AutoMem service - Deploy the backend (see options above)
Install MCP client - Connect your AI platforms

AutoMem Service Setup

Before installing the MCP client, you need a running AutoMem service (the backend). Choose your deployment option:

Option 1: Local Development (Recommended for Getting Started)

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

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

Service runs at http://localhost:8001 with no authentication required.

👉 Full Local Setup Guide

Option 2: Railway Cloud (Recommended for Production)

Best for: Multi-device access, team collaboration, always-on availability.

One-click deploy with $5 free credits. Typical cost: ~$0.50-1/month.

👉 Full Railway Deployment Guide

Option 3: Self-Hosted Production

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

Deploy via Docker Compose, Kubernetes, or any container platform.

👉 Deployment Options

MCP Client Setup

Now that your AutoMem service is running, install and configure the MCP client to connect your AI platforms.

Supported Platforms:

Claude Desktop - Desktop AI assistant
Cursor IDE - AI-powered code editor
Claude Code - Terminal coding assistant with automation hooks
GitHub Copilot coding agent - Cloud-based coding agent on GitHub.com
GitHub Copilot CLI and VS Code - Terminal and editor with hooks and memory rules
OpenAI Codex - CLI, IDE, and cloud agent
Hermes Agent - Nous Research terminal agent with MCP and native memory provider support
Grok Build - xAI Grok CLI with native ~/.grok/config.toml MCP registration
Google Antigravity - Desktop editor with MCP Store and raw config
OpenClaw - Personal AI assistant with multi-platform messaging (WhatsApp, Telegram, Slack, Discord, etc.)

Remote MCP via HTTP (Sidecar)

Use this option to connect AutoMem to cloud products that support remote MCP via Streamable HTTP (recommended) or SSE transport, including ChatGPT (Developer Mode), Claude.ai on the web, Claude Mobile (iOS/Android), and ElevenLabs Agents.

When to use the remote MCP sidecar

You want AutoMem in ChatGPT's Developer Mode connectors
You use Claude.ai on the web or the Claude mobile app
You integrate with ElevenLabs real‑time Agents
You need an HTTPS endpoint instead of a local process

Deploy the remote MCP sidecar

Deploy the AutoMem remote MCP sidecar on Railway (one‑click) or any Docker platform. It supports both Streamable HTTP (recommended) and SSE transports, proxies MCP over HTTPS, and connects to your AutoMem service.

Guide: Remote MCP Sidecar (AutoMem service repo)

Required env vars for the sidecar:

AUTOMEM_API_URL — URL to your AutoMem service (prefer internal URL on Railway, e.g. http://memory-service.railway.internal:8001)
AUTOMEM_API_TOKEN — Token for your AutoMem service (if enabled)

Sidecar endpoints:

POST /mcp — Streamable HTTP (recommended) — full-duplex MCP-over-HTTP
GET /mcp/sse — SSE stream (legacy) — server → client events
POST /mcp/messages?sessionId=<id> — SSE client → server JSON-RPC (legacy)
GET /health — Health probe

Configure platforms

ChatGPT (Developer Mode)

Enable Developer Mode → Settings → Connectors → Advanced
Add a custom MCP server with this URL:
- Streamable HTTP (recommended): https://<your-mcp-domain>/mcp?api_token=<AUTOMEM_API_TOKEN>
- SSE (legacy): https://<your-mcp-domain>/mcp/sse?api_token=<AUTOMEM_API_TOKEN>
Save and test: ask ChatGPT to "Check the health of the AutoMem service".

Configure ChatGPT Developer Mode with your MCP endpoint (HTTP or SSE)

ChatGPT showing the custom connector enabled

ChatGPT using AutoMem tools via remote MCP

Notes:

ChatGPT requires URL‑based auth for custom connectors → include ?api_token=... in the URL

Claude.ai (Web)

Streamable HTTP (recommended): https://<your-mcp-domain>/mcp?api_token=<AUTOMEM_API_TOKEN>
SSE (legacy): https://<your-mcp-domain>/mcp/sse?api_token=<AUTOMEM_API_TOKEN>
Then chat with Claude on the web; ask it to recall or store memories.

Claude.ai connected to AutoMem via remote MCP

Claude Mobile (iOS/Android)

Streamable HTTP (recommended): https://<your-mcp-domain>/mcp?api_token=<AUTOMEM_API_TOKEN>
SSE (legacy): https://<your-mcp-domain>/mcp/sse?api_token=<AUTOMEM_API_TOKEN>
Open the Claude mobile app and add the remote MCP connector.

Claude mobile app connected to AutoMem via remote MCP

ElevenLabs Agents

Use either header‑based auth (recommended) or URL token:

Streamable HTTP (recommended):
- Server URL: https://<your-mcp-domain>/mcp
- Header: Authorization: Bearer <AUTOMEM_API_TOKEN>
- Or use URL token: https://<your-mcp-domain>/mcp?api_token=<AUTOMEM_API_TOKEN>
SSE (legacy):
- Server URL: https://<your-mcp-domain>/mcp/sse
- Header: Authorization: Bearer <AUTOMEM_API_TOKEN>
- Or use URL token: https://<your-mcp-domain>/mcp/sse?api_token=<AUTOMEM_API_TOKEN>

Troubleshooting (Remote MCP)

Common fixes from the sidecar guide:

Ensure your memory service listens on PORT=8001
On Railway, prefer internal DNS: http://memory-service.railway.internal:8001
Check sidecar logs for errors (e.g., railway logs --service automem-mcp-sse)
As a fallback, set AUTOMEM_API_URL to the public URL of your memory service

For deeper details, see the AutoMem service docs linked above.

Guided Setup Wizard

After deploying the AutoMem service, use the setup wizard to configure your MCP client:

npx @verygoodplugins/mcp-automem setup

The wizard will:

Prompt for your AutoMem endpoint (http://localhost:8001 or Railway URL)
Prompt for API key (if using Railway)
Create/update .env file in current directory
Print config snippets for your platform
Validate connection to AutoMem service

Example:

$ npx @verygoodplugins/mcp-automem setup
? AutoMem Endpoint: http://localhost:8001
? API Key (optional): [leave blank for local]
✓ Connection successful!
✓ Config saved to .env
✓ Claude Desktop config snippet generated

Claude Desktop

1. Install MCP Server

Add AutoMem to your Claude Desktop configuration:

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

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@verygoodplugins/mcp-automem"],
      "env": {
        "AUTOMEM_API_URL": "https://your-automem-instance.railway.app",
        "AUTOMEM_API_KEY": "your-api-key-if-required"
      }
    }
  }
}

For local development:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@verygoodplugins/mcp-automem"],
      "env": {
        "AUTOMEM_API_URL": "http://127.0.0.1:8001"
      }
    }
  }
}

2. Restart Claude Desktop

Restart Claude Desktop to load the MCP server.

3. Verify Installation

In Claude Desktop, ask:

Check the health of the AutoMem service

You should see connection status for FalkorDB and Qdrant.

4. Add Personal Preferences (Optional but Recommended)

Teach Claude Desktop when to recall, store, update, and associate memories by adding the AutoMem starter template to Claude's Personal Preferences.

As of April 2026, Claude Desktop's UI labels this area Personal Preferences:

Open Claude Desktop.
Open Settings.
Go to Profile → Personal Preferences.
Paste the starter template from templates/CLAUDE_DESKTOP_INSTRUCTIONS.md.
Click Save, then restart Claude Desktop.

The template assumes your MCP server key is memory, so tool names look like mcp__memory__recall_memory. If you configured a different key in claude_desktop_config.json, update the tool prefix in the pasted template.

On macOS, from this repository, you can copy just the paste-ready part of the template with:

awk 'seen { print } /^---$/ { seen = 1 }' templates/CLAUDE_DESKTOP_INSTRUCTIONS.md | pbcopy

Add the AutoMem starter template to Personal Preferences

What the template does:

Semantic-first recall: Claude pulls preferences first, then runs one targeted semantic recall using the real nouns in your message. It avoids project tag gates on turn 1 unless the scope is explicit.
Lower-noise storage: Claude stores only durable preferences, stabilized decisions, named patterns, and significant fixes. It skips session summaries and speculative "might matter later" notes.
Graph hygiene: Important stores run a recall → store → verify → associate ritual so memory does not degrade into a flat bag of notes.

For the full paste-ready text, use templates/CLAUDE_DESKTOP_INSTRUCTIONS.md. For Claude Code's ~/.claude/CLAUDE.md path, use templates/CLAUDE_MD_MEMORY_RULES.md instead.

Claude Desktop using AutoMem from Personal Preferences

Cursor IDE

1. One-Click Install (Fastest)

Click to install AutoMem MCP server in Cursor:

What this does:

Automatically adds AutoMem MCP server to Cursor's configuration
No manual JSON editing required!

After installation:

Update AUTOMEM_API_URL with your AutoMem instance URL in ~/.cursor/mcp.json
Optionally set AUTOMEM_API_KEY if using authentication
Restart Cursor to load the server

2. Add Memory Rule (Recommended)

Install the automem.mdc rule file to teach Cursor how to use memory:

npx @verygoodplugins/mcp-automem cursor

This will:

Auto-detect your project name and description
Create .cursor/rules/automem.mdc with memory-first instructions
Check for MCP server configuration and provide setup guidance if missing

Options:

# Specify project details manually
npx @verygoodplugins/mcp-automem cursor --name my-project --desc "My awesome project"

# Preview changes without modifying files
npx @verygoodplugins/mcp-automem cursor --dry-run

# Custom target directory
npx @verygoodplugins/mcp-automem cursor --dir .cursor/rules

3. How Cursor Loads Instructions

Cursor can stack multiple instruction layers at once:

User Rules: Global rules from Cursor Settings > General > Rules for AI
Project Rules: Repo-scoped rules in .cursor/rules/*.mdc
Custom Modes: Mode-specific instructions for plan/debug/review/refactor flows

Recommended AutoMem split:

User Rules: Thin global style/autonomy/preferences recall
Project Rules: Operational memory workflow for the current repo
Custom Modes: Task-shape guidance only; do not restate memory policy

4. Global User Rules (Optional)

For cross-project preference recall and a stable collaboration baseline, copy the thin template in templates/cursor/user-rules.md into Cursor Settings > General > Rules for AI:

Click to expand: Thin Global User Rules for Cursor

Keep responses direct, concise, and high-signal.
If the next step is clear, reversible, and low-risk, proceed without asking.
When collaboration style, tone, autonomy, or coding preferences materially affect the work, run a semantic recall for preferences, for example: personal coding preferences <project-name> collaboration style.
Use recalled memory as context, not ground truth.
If recalled memory conflicts with the current repo state or the latest user instruction, current evidence wins.
Keep this layer thin. Project rules should own project-specific memory workflow.

Keep this global layer short. Project rules should continue to own recall/store/update/associate behavior, tagging, and the GPT-5.4 project overlay. For full operational memory behavior, use project-level installation.

Claude Code

The recommended install is the AutoMem plugin — Claude Code handles install, updates, configuration prompts, and uninstall natively. A settings-level CLI installer remains for environments without plugin support.

Option A: Plugin (Recommended)

# In Claude Code:
/plugin marketplace add verygoodplugins/mcp-automem
/plugin install automem@verygoodplugins-mcp-automem

When you enable the plugin, Claude Code prompts for:

AutoMem API URL — e.g. http://127.0.0.1:8001 or your Railway URL. Leave empty to use AUTOMEM_API_URL from your environment; falls back to http://127.0.0.1:8001.
AutoMem API key — only if your deployment requires auth. Stored in the system keychain.

The plugin bundles the MCP server, silent integration hooks (SessionStart recall plus store tracking), and the memory-management skill plus /memory-recall, /memory-store, and /memory-health commands. It does not register a Stop hook by default, so normal sessions end without AutoMem feedback in the chat stream.

Tool naming: Claude Code namespaces plugin MCP tools, so they appear as mcp__plugin_automem_memory__store_memory (etc.) rather than mcp__memory__*. Approve each tool on first use, or pre-approve by adding the mcp__plugin_automem_memory__* names to permissions.allow in ~/.claude/settings.json.

Migrating from the CLI installer: remove the settings-level install first, so hooks don't fire twice and the memory tools don't appear under two servers:

npx @verygoodplugins/mcp-automem uninstall claude-code --clean-all

Option B: CLI installer (settings-level)

For locked-down environments without plugin support, or if you prefer hooks and permissions written directly into ~/.claude/:

1. Configure MCP Server

Add AutoMem to ~/.claude.json:

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

2. Install hooks and permissions

npx @verygoodplugins/mcp-automem claude-code

This installs the hook scripts and merges the six mcp__memory__* tool permissions into ~/.claude/settings.json so Claude can use memory tools without asking. The default profile registers only SessionStart recall and PostToolUse store tracking; the Stop storage nudge script is installed but not registered, so session end stays silent. That permission list is everything the installer grants — it no longer ships any Bash(*), file-tool, or deny/ask entries.

To opt back into the visible Stop storage nudge:

npx @verygoodplugins/mcp-automem claude-code --profile nudged

Re-running setup is also the supported migration path for legacy installs: the default silent merge removes the managed AutoMem Stop nudge from settings unless you pass --profile nudged, and removes retired hooks in every historical spelling — the old session-memory.sh Stop entry, the mechanical capture-*.sh PostToolUse hooks, and the queue Stop machinery (queue-cleanup.sh plus the mcp-automem queue drainer in its npx and bare-CLI forms; nothing writes to the queue anymore, so draining it per-session was dead weight). It also deletes the retired script files those hooks used from ~/.claude/hooks and ~/.claude/scripts, collapses duplicate hook registrations, and strips the four hook-era permission grants the old template shipped for that machinery (Bash(python3:*), Bash(python:*), Bash(py:*), Bash(jq:*)). Generic grants like Bash(git:*) or Edit that earlier templates added are treated as user-owned and never touched — remove them yourself if you don't want them. Hooks the installer didn't author are never touched, and a backup (settings.json.bak, numbered if needed) is written before any change. The mcp-automem queue CLI remains available for manually draining a queue file.

Windows compatibility note: the Claude Code hook payload remains Bash-based. On Windows, use a POSIX shell environment such as Git Bash, MSYS2, or WSL with bash available (the hooks are pure bash+sed — Python and jq are no longer required). This is not full native Windows hook support yet.

Or manually add the permissions to ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__memory__store_memory",
      "mcp__memory__recall_memory",
      "mcp__memory__associate_memories",
      "mcp__memory__update_memory",
      "mcp__memory__delete_memory",
      "mcp__memory__check_database_health"
    ]
  }
}

Add Memory Rules (both options)

Append memory instructions to ~/.claude/CLAUDE.md:

cat templates/CLAUDE_MD_MEMORY_RULES.md >> ~/.claude/CLAUDE.md

This teaches Claude when to recall (session start, before decisions) and what to store (decisions, patterns, insights).

Verify Installation

Ask Claude Code:

Check the health of the AutoMem service

See Claude Code Integration Guide for more details.

Tool search and deferred loading

Claude Code defers MCP tool schemas behind its ToolSearch tool by default. The AutoMem server marks store_memory, recall_memory, and associate_memories as always-loaded (via anthropic/alwaysLoad in each tool's _meta), so the tools the memory rules invoke on every session are available without a search step on Claude Code v2.1.121+. The maintenance tools (update_memory, delete_memory, check_database_health) stay deferred and are discovered on demand.

On older Claude Code versions, you can load the whole server upfront instead by setting "alwaysLoad": true on the server entry in ~/.claude.json:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@verygoodplugins/mcp-automem"],
      "alwaysLoad": true
    }
  }
}

GitHub Copilot coding agent (GitHub.com)

GitHub Copilot coding agent on GitHub.com supports MCP servers configured per repository.

Plans and availability

Copilot Pro / Pro+: Copilot coding agent is enabled by default.
Copilot Business / Enterprise: Copilot coding agent and third-party MCP servers are disabled by default and must be enabled by an admin (policies: Copilot coding agent and MCP servers on GitHub.com).

References:

1. Create a Copilot environment secret (recommended)

For API keys, use the repository's copilot environment secrets (instead of pasting secrets into JSON). GitHub Copilot MCP configuration supports passing secrets to a local MCP server via environment variables.

Create an environment secret named COPILOT_MCP_AUTOMEM_API_KEY with your AutoMem API key.

2. Add the MCP configuration to your repository

In your GitHub repository: Settings → Copilot → Coding agent → MCP configuration, paste:

{
  "mcpServers": {
    "memory": {
      "type": "local",
      "tools": ["*"],
      "command": "npx",
      "args": ["-y", "@verygoodplugins/mcp-automem"],
      "env": {
        "AUTOMEM_API_URL": "https://xxxx.up.railway.app",
        "AUTOMEM_API_KEY": "COPILOT_MCP_AUTOMEM_API_KEY"
      }
    }
  }
}

Notes:

AUTOMEM_API_URL must be reachable from GitHub's hosted environment (so localhost typically won't work).
GitHub Copilot coding agent supports MCP tools (not resources/prompts), and supports MCP server types "local", "http", and "sse".

Optional: organization/enterprise-level setup (custom agents)

GitHub also supports organization/enterprise-level custom agents stored in a .github-private repository (with agent profiles in an agents/ directory). Organization/enterprise owners can configure MCP servers in those agents via YAML front matter (mcp-servers), while repository-level agents (in the .github/agents/ directory — note: .github is intentionally lowercase) can only use MCP servers configured in the repository settings above.

Optional: connect via remote MCP (HTTP/SSE “bridge”)

If you deploy the optional remote MCP sidecar (see “Remote MCP via HTTP” in the README), you can connect Copilot to it via "http" (Streamable HTTP) or "sse".

Example (Streamable HTTP):

{
  "mcpServers": {
    "memory": {
      "type": "http",
      "url": "https://<your-mcp-domain>/mcp",
      "tools": ["*"],
      "headers": {
        "Authorization": "$COPILOT_MCP_AUTOMEM_AUTH_HEADER"
      }
    }
  }
}

Create a COPILOT_MCP_AUTOMEM_AUTH_HEADER environment secret with the full header value (for example: Bearer <AUTOMEM_API_TOKEN>).

GitHub Copilot CLI and VS Code

GitHub Copilot CLI and VS Code Copilot both use the Copilot config directory ($COPILOT_HOME when set, otherwise ~/.copilot/) and the same hooks system. The copilot setup command installs hooks, support scripts, and memory rules that work in both surfaces.

For details on how hooks work across both surfaces, see the hooks reference.

1. Configure MCP Server

The MCP server config lives in different places for CLI vs VS Code:

Copilot CLI -- add to $COPILOT_HOME/mcp-config.json or ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "automem": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@verygoodplugins/mcp-automem"],
      "env": {
        "AUTOMEM_API_URL": "http://127.0.0.1:8001",
        "AUTOMEM_API_KEY": "your-api-key-if-required"
      },
      "tools": ["*"]
    }
  }
}

Note: Copilot CLI does not support ${env:...} variable interpolation in mcp-config.json -- that syntax is VS Code-only. Environment variables set in your shell (e.g. AUTOMEM_API_KEY) are inherited by the MCP server process automatically, so you can omit them from the env block. Only include values that are not already in your shell environment.

VS Code -- add to .vscode/mcp.json (workspace) or VS Code user settings:

{
  "servers": {
    "automem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@verygoodplugins/mcp-automem"],
      "env": {
        "AUTOMEM_API_URL": "http://127.0.0.1:8001",
        "AUTOMEM_API_KEY": "your-api-key-if-required"
      }
    }
  }
}

2. Install Hooks and Memory Rules

npx @verygoodplugins/mcp-automem copilot --yes

This installs:

Hook JSON files into $COPILOT_HOME/hooks/ or ~/.copilot/hooks/ (session-start recall, a postToolUse store tracker, and -- with --profile full -- an opt-in agentStop storage nudge)
Support scripts (bash + PowerShell) into $COPILOT_HOME/scripts/ or ~/.copilot/scripts/
Memory rules into both copilot-instructions.md (CLI) and instructions/automem.instructions.md (VS Code) inside the target Copilot directory

Re-running the command also deletes the orphaned files from the retired session-summary + build/test/deploy capture + queue machinery left behind by older installs (parity with the Claude Code side).

Option	Default	Description
`--format cli\|vscode\|both`	`both`	Which memory rules and hook event names to install. `cli` = camelCase hooks + CLI rules only. `vscode` = PascalCase hooks + VS Code rules only. `both` = both hook event spellings + both rule sets.
`--profile lean\|full`	`lean`	`lean` (default, silent) = session-start recall + `postToolUse` store tracker. `full` = adds the opt-in `agentStop` storage nudge that re-wakes the agent for one closing turn (once per session) when nothing durable was stored.
`--dir <path>`	`$COPILOT_HOME` or `~/.copilot`	Target installation directory
`--dry-run`		Preview changes without writing files
`--yes`		Skip confirmation prompts
`--quiet`		Suppress output
`--help`, `-h`		Print the usage block and exit without installing

Nudge note: Copilot's agentStop output contract is {decision, reason} -- a block decision re-prompts the agent using reason. Unlike Claude Code's Stop hook it cannot inject hidden, non-prompting context, so the storage nudge is opt-in (--profile full) only; the default lean install keeps session end silent. The nudge fires at most once per session and only after a substantive session (>= 5 user.message turns in the transcript).

Windows note: All hook templates invoke PowerShell with -NoProfile to prevent profile output from corrupting hook JSON payloads. This matches how bash hooks work (non-interactive bash script.sh skips ~/.bashrc). If your hook scripts need something from your profile (custom PATH entries, modules), move that setup into the hook script itself or into environment variables.

3. Verify Installation

In a Copilot CLI or VS Code Copilot session, ask:

Check the health of the AutoMem service

4. Uninstall

npx @verygoodplugins/mcp-automem uninstall copilot --yes

Add --clean-all to also remove the MCP server entry from the target Copilot mcp-config.json.

OpenAI Codex

OpenAI Codex is an AI coding assistant with CLI, IDE, and cloud agent support. AutoMem enables Codex to remember project context, coding patterns, and past decisions.

1. Install Codex CLI

If you haven't already, install Codex:

# Using npm
npm install -g @openai/codex

# Or using Homebrew (macOS)
brew install codex

2. Authenticate

codex
# Sign in with your ChatGPT account when prompted
# Requires ChatGPT Plus, Pro, Team, Edu, or Enterprise

3. Configure MCP Server

Add AutoMem to your Codex configuration file.

Config location: ~/.codex/config.toml

Add the following to your config.toml:

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

[mcp_servers.memory.env]
AUTOMEM_API_URL = "https://your-automem-instance.railway.app"
AUTOMEM_API_KEY = "your-api-key-if-required"

For local development:

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

[mcp_servers.memory.env]
AUTOMEM_API_URL = "http://127.0.0.1:8001"

Using local build (for development):

[mcp_servers.memory]
command = "/opt/homebrew/bin/node"  # or "/usr/bin/node" on Linux
args = ["/path/to/mcp-automem/dist/index.js"]

[mcp_servers.memory.env]
AUTOMEM_API_URL = "https://your-automem-instance.railway.app"
AUTOMEM_API_KEY = "your-api-key"

3.5. Add Memory Rules (Optional but recommended)

Install memory-first rules into your project so Codex proactively recalls and stores context:

npx @verygoodplugins/mcp-automem codex

This creates or updates AGENTS.md with an AutoMem section tailored to your project.

4. Restart Codex

Restart the Codex CLI or reload your IDE extension to load the MCP server.

5. Verify Installation

Ask Codex:

Check the health of the AutoMem service

You should see connection status for FalkorDB and Qdrant.

How to Use with Codex

In the CLI:

cd ~/Projects/my-app

# Ask Codex to use memory
codex "What were the key decisions made in this project last week?"

In the IDE:

Open Codex panel in your editor
Ask questions that leverage memory
Codex will automatically use AutoMem tools when relevant

In Cloud Agent:

Launch tasks from chatgpt.com/codex
Codex has access to stored memories across environments
Memories sync between CLI, IDE, and cloud agent

Memory Best Practices for Codex

Store project-scoped memories with bare tags:

mcp__memory__store_memory({
  content: "Implemented OAuth flow using NextAuth.js in my-app",
  type: "Pattern",
  tags: ["my-app", "auth", "nextauth"],
  importance: 0.8,
  confidence: 0.8,
});

Store architectural decisions:

mcp__memory__store_memory({
  content:
    "Decided to use server components for data fetching in Next.js 14. Reason: Better performance and SEO.",
  type: "Decision",
  tags: ["decision", "my-app", "nextjs"],
  importance: 0.9,
  confidence: 0.9,
});

Recall preferences first, then semantic task context:

mcp__memory__recall_memory({
  tags: ["preference"],
  limit: 20,
  sort: "updated_desc",
  format: "detailed",
});

mcp__memory__recall_memory({
  query: "setup instructions deployment process Railway Next.js",
  tags: ["my-app"],   // drop if the slug is ambiguous
  time_query: "last 90 days",
  limit: 30,
  format: "detailed",
});

Integration with GitHub

Since Codex integrates with GitHub repositories:

Memories persist across branches
Track decisions made during PRs
Remember why code was written a certain way
Recall past discussions about implementations

Example workflow:

Codex analyzes PR and stores key decisions
Future coding sessions recall those decisions
Consistent implementation across team members

Cross-Platform Memory Sync

Memories stored in Codex are available in:

Cursor IDE (via AutoMem MCP)
Claude Code (via AutoMem MCP)
Claude Desktop (via AutoMem MCP)

Use consistent project names and tags across platforms. Use consistent bare project slugs and category tags across platforms; avoid platform tags and date tags.

Hermes Agent

Hermes can use AutoMem either as normal MCP tools, as Hermes' native memory provider, or as both. The default is MCP-only because it exposes one explicit tool path and avoids collisions with Hermes' built-in memory tools.

Hermes memory providers are exclusive plugins. That means they are activated through memory.provider, not through plugins.enabled. If hermes plugins list shows AutoMem as not enabled or exclusive plugin, that is expected for provider mode. Use hermes memory status as the source of truth.

AutoMem integrations use one shared AutoMem recall blueprint across hosts: preference recall first, one semantic task-context recall with a 90-day window, and debug/topic-shift recall only when triggered. Instruction-driven hosts use the rules profile (20 / 30 / 20 for preference/context/debug limits). Runtime provider hosts use the provider profile (5 / 10 / 10) so injected context stays compact while preserving the same recall semantics.

1. Choose an install mode

# MCP tools only: exposes mcp_automem_recall_memory, mcp_automem_store_memory, etc.
npx @verygoodplugins/mcp-automem hermes --mode mcp

# Native memory provider: activates AutoMem through memory.provider.
npx @verygoodplugins/mcp-automem hermes --mode provider

# Advanced: native ambient recall plus MCP write/recall tools.
npx @verygoodplugins/mcp-automem hermes --mode both

--mode both keeps explicit tools on the MCP path only and writes AUTOMEM_HERMES_PROVIDER_TOOLS=false so Hermes does not expose duplicate automem_* provider tools.

2. Verify

# MCP mode
hermes mcp test automem

# Provider or both mode
hermes memory status
hermes automem doctor

Then restart Hermes and ask it to check AutoMem health. In MCP mode, Hermes should expose mcp_automem_check_database_health and should not expose delete_memory by default.

In provider mode, hermes memory status should show Provider: automem and Status: available. hermes automem doctor checks the configured AutoMem /health endpoint and runs a small recall-prefetch probe. Recall context is injected into the model payload before a turn; Hermes does not print that context in the terminal UI by default.

Provider explicit recall is capped at 10 results in Hermes provider mode to keep accidental broad recalls from flooding a model turn. Ambient provider prefetch uses the provider profile: up to 5 preference memories, 10 task-context memories, and 10 debug memories, with the same 90-day task-context window used by the rules profile.

3. See what recall injects

Provider recall is injected into the model payload before each turn and is not printed in the terminal. To see the exact block AutoMem sends, run debug-recall with any prompt:

hermes automem debug-recall "what do you remember about my setup?"

Hermes debug logs intentionally report only section counts and recall status, not memory content. debug-recall is the supported way to inspect the actual <memory-context> block. First-turn task-context recall uses the cwd project tag only when the prompt is not an explicit/general memory ask, or when that prompt names the cwd project. For general questions like do we like Example Contact?, Hermes drops the cwd tag and relies on semantic recall instead of hard-gating to the current repo.

The real <memory-context> block — preferences first, then task context — that ambient recall injects ahead of the turn. Add --raw for the unfenced text. (Shown against a synthetic demo dataset.)

Once recall is wired up, a one-shot turn answers straight from it. Here the staging port exists only in the recalled memory, so a correct answer is proof that recall fired:

hermes -z pulls the seeded fact out of recall and answers Port 7341.

Maintainers: both visuals are regenerated against an isolated, freshly seeded demo stack with npm run docs:hermes (see scripts/build-hermes-demos.mjs). They never capture a personal corpus.

4. Uninstall

npx @verygoodplugins/mcp-automem uninstall hermes

# Preview without changing files
npx @verygoodplugins/mcp-automem uninstall hermes --dry-run

# Strip the AutoMem rules block from a custom rules file
# (mirrors `hermes --rules <path>` at install time; defaults to $HERMES_HOME/AGENTS.md)
npx @verygoodplugins/mcp-automem uninstall hermes --rules /path/to/AGENTS.md

The Hermes uninstaller removes AutoMem's current config and known pre-release install targets, including mcp_servers.automem, AutoMem-owned mcp_servers.memory, memory.provider: automem, $HERMES_HOME/plugins/automem, AutoMem Hermes rules, and AutoMem keys in $HERMES_HOME/.env. Pass --rules <path> if you installed the rules block into a non-default file so the uninstaller strips that file instead of $HERMES_HOME/AGENTS.md.

Hermes setup also removes a stale AutoMem Codex rules block from $HERMES_HOME/AGENTS.md. That pre-release block mentioned Codex/Claude-style mcp__memory__* tool names and can steer provider-only Hermes sessions toward the wrong namespace.

Troubleshooting

If Anthropic returns tools: Tool names must be unique, Hermes is seeing two explicit AutoMem tool surfaces. The usual pre-release cause is a stale mcp_servers.memory AutoMem entry combined with mcp_servers.automem or provider tools. Run:

npx @verygoodplugins/mcp-automem uninstall hermes
npx @verygoodplugins/mcp-automem hermes --mode mcp

For advanced both mode, confirm $HERMES_HOME/.env contains AUTOMEM_HERMES_PROVIDER_TOOLS=false.

If provider mode appears active but recall still seems absent, run:

AUTOMEM_HERMES_DEBUG=true hermes

Then check the Hermes logs for AutoMem prefetch diagnostics. The debug path reports counts and endpoint status only; it does not dump memory content or secrets.

Grok Build

Grok Build (xAI CLI) loads MCP from ~/.grok/config.toml, then Claude/Cursor compat sources. Native config is required for AutoMem. If AutoMem is only present via Claude/Cursor imports, Grok can start npx @verygoodplugins/mcp-automem without AUTOMEM_* env — the server then defaults to http://127.0.0.1:8001 and every session fails with Mcp error: -32603: fetch failed. Edits in the /mcps UI are session-scoped unless written to config.toml.

Install

# Guided installer (detects ~/.grok and offers Grok in the agent list)
npx @verygoodplugins/mcp-automem install --clients grok \
  --endpoint https://your-automem.example --api-key "$AUTOMEM_API_KEY"

# Or standalone
npx @verygoodplugins/mcp-automem grok \
  --endpoint https://your-automem.example --api-key "$AUTOMEM_API_KEY"

This writes:

~/.grok/config.toml → [mcp_servers.memory] with npx -y @verygoodplugins/mcp-automem and AUTOMEM_API_URL / AUTOMEM_API_KEY / AUTOMEM_PROCESS_TAG=grok:memory
~/.grok/AGENTS.md → marked AutoMem rules block (Grok injects this every session)

Override the Grok home with $GROK_HOME or --dir.

Only the [mcp_servers.memory] table is touched — the rest of config.toml keeps its comments, multi-line strings, and formatting. Every write backs the file up first, and --dry-run reports whether the entry would be added, updated, or left unchanged without writing anything. To wire it up by hand instead, copy templates/grok/config.toml.

If disabled_mcp_servers in config.toml contains "memory", Grok ignores the server entry entirely. The installer warns when it sees this; remove the name from that list.

Verify

grok mcp list
# → memory: npx -y @verygoodplugins/mcp-automem

# Start a *new* Grok session (existing sessions keep the old MCP child), then recall

Tools appear as memory__recall_memory, memory__store_memory, etc. Discover with search_tool, then call with use_tool.

Uninstall

npx @verygoodplugins/mcp-automem uninstall grok
npx @verygoodplugins/mcp-automem uninstall grok --dry-run

Removes AutoMem-owned mcp_servers.memory and strips the  block from ~/.grok/AGENTS.md (or --rules <path>). Non-AutoMem memory servers are left alone.

Troubleshooting

Symptom	Cause	Fix
`fetch failed` / `ECONNREFUSED 127.0.0.1:8001`	No native MCP env; compat import dropped `AUTOMEM_*`	Run `mcp-automem grok` so `config.toml` wins over Claude/Cursor
Works after `/mcps` SSE tweak, fails next session	UI change was session-only	Persist with `grok mcp add` / `mcp-automem grok`, not the modal alone
`grok mcp list` empty but tools still appear	Compat-only load	Add native `[mcp_servers.memory]` so env is explicit

Google Antigravity

Google Antigravity supports MCP servers through its built-in MCP Store and a raw config file. AutoMem fits Antigravity's local stdio MCP flow directly, so the primary path is to add the memory server to Antigravity's custom MCP server config.

1. Open Antigravity's MCP raw config

Antigravity's own MCP docs currently describe this flow:

Open the MCP Store via the ... dropdown at the top of the editor's agent panel
Click Manage MCP Servers
Click View raw config
Edit mcp_config.json

Config location: ~/.gemini/antigravity/mcp_config.json

2. Add the AutoMem MCP server

Paste the following as the full contents of ~/.gemini/antigravity/mcp_config.json, or merge the memory entry into your existing mcpServers object.

You can also copy it directly from templates/antigravity/mcp_config.json.

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@verygoodplugins/mcp-automem"],
      "env": {
        "AUTOMEM_API_URL": "https://your-automem-instance.railway.app",
        "AUTOMEM_API_KEY": "your-api-key-if-required"
      }
    }
  }
}

For local development:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@verygoodplugins/mcp-automem"],
      "env": {
        "AUTOMEM_API_URL": "http://127.0.0.1:8001"
      }
    }
  }
}

3. Reload Antigravity

Restart Antigravity, or reload the MCP configuration from the MCP Store, so the memory server is picked up.

4. Verify installation

Confirm the memory server appears in Antigravity's MCP server list, then ask Antigravity:

Check the health of the AutoMem service

You should see connection status for FalkorDB and Qdrant.

Optional: use the remote MCP sidecar instead

Antigravity's MCP config also supports remote Streamable HTTP servers via serverUrl, so you can use the optional AutoMem remote sidecar if you want an HTTPS MCP endpoint instead of a local npx process.

Use the local stdio configuration above as the default path. Reach for remote MCP only if you specifically want the sidecar model described in Remote MCP via HTTP (Sidecar).

Installation Methods

Option 1: Using NPX (Recommended)

No installation required:

# For Claude Desktop (in config)
"command": "npx",
"args": ["-y", "@verygoodplugins/mcp-automem"]

# For Claude Code
claude mcp add memory "npx -y @verygoodplugins/mcp-automem"

Option 2: Global Installation

Install once, use anywhere:

# Install globally
npm install -g @verygoodplugins/mcp-automem

# For Claude Code
claude mcp add memory "mcp-automem"

Option 3: Local Development

For contributing or customization:

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

OpenClaw

OpenClaw is a personal AI assistant that runs locally and supports 11+ messaging platforms (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Teams, Matrix, Zalo, etc.).

AutoMem now supports three OpenClaw integration modes, in this recommended order:

plugin - native OpenClaw plugin with typed AutoMem tools and DM-only auto-recall by default
mcp - workspace/shared mcporter setup with the same typed AutoMem tools
skill - legacy curl fallback

Quick Setup

Install OpenClaw (2026.x or later):

curl -fsSL https://openclaw.ai/install.sh | bash

Start AutoMem service (local or Railway):

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

Run the recommended setup:
```
curl -fsSL https://automem.ai/install.sh | bash
```
Local-build equivalent while developing this repo:
```
./install.sh
```
Open OpenClaw. The installer will restart the gateway, verify the plugin, and open or print the dashboard URL.

The recommended setup command above installs OpenClaw in plugin mode using the packaged flow from @verygoodplugins/mcp-automem (under the hood: npx @verygoodplugins/mcp-automem openclaw --mode plugin). That stages a lean native plugin package and keeps memory-core as OpenClaw's active memory slot instead of replacing it. Plugin mode also enables the /plugins chat command so users can verify and inspect the install from inside OpenClaw. It also appends the AutoMem tool names to tools.alsoAllow, which keeps them callable even when OpenClaw is using a restrictive base profile such as tools.profile = "coding" without forcing a restrictive global allowlist. On fresh installs, it also probes AutoMem once: if the service is reachable and already contains memory, the installer sets agents.defaults.skipBootstrap = true so OpenClaw skips the name/timezone/vibe bootstrap flow. If AutoMem is empty or unavailable, the normal bootstrap remains in place. When AutoMem already knows the user, the installer also hydrates a compact startup profile from memory so the first browser chat can behave like a returning user agent conversation instead of a generic blank slate.

For a deterministic dogfood pass, see the scripted clean-install demo in templates/openclaw/OPENCLAW_SETUP.md.

Alternate modes

# Transparent typed-MCP path
npx @verygoodplugins/mcp-automem openclaw --mode mcp --workspace ~/clawd

# Legacy curl fallback
npx @verygoodplugins/mcp-automem openclaw --mode skill --workspace ~/clawd

Why OpenClaw + AutoMem?

Multi-platform memory: Your agent remembers decisions across WhatsApp, Telegram, Slack, Discord, and other OpenClaw channels
Native plugin option: New installs can use OpenClaw's plugin system instead of only curl-based skills
Lower-friction onboarding: Populated AutoMem installs can start with memory-aware context immediately instead of redoing first-run bootstrap questions
Transparent MCP option: mcp mode writes a normal mcporter.json and keeps secrets out of it
Shared memory-policy parity: OpenClaw now follows the same validated AutoMem policy as Claude Desktop, Claude Code, and Cursor
Targeted recall instead of every-turn recall: preference recall on the first substantive turn (limit 20), semantic task recall on that turn (limit 30, last 90 days), then bugfix recall only for active debugging
Semantic-first recall: OpenClaw only uses installer defaultTags as an unambiguous project gate for first-turn task recall instead of hard-gating every turn
Optional full replacement mode: --replace-memory disables memory-core, disables the bundled session-memory hook, and turns off dreaming so AutoMem becomes the only memory system
Complementary memory layers: memory-core remains useful for local file memory; AutoMem is the semantic graph layer

Use https://automem.ai/install.sh for the OpenClaw happy path, or npx @verygoodplugins/mcp-automem openclaw --mode plugin when you need the raw CLI. Do not point openclaw plugins install at the main @verygoodplugins/mcp-automem package directly.

Full Setup Guide

For mode-by-mode setup, migration notes, and troubleshooting:

AutoMem + OpenClaw Integration Guide

Configuration

Environment Variables

Create .env file or set in your shell:

# Required: AutoMem service URL
AUTOMEM_API_URL=https://your-automem-instance.railway.app

# Optional: API key for authenticated instances
AUTOMEM_API_KEY=your_api_key_here

Deprecated alias: AUTOMEM_ENDPOINT is the previous name for this variable. It still works (the server falls back to it when AUTOMEM_API_URL is unset), but new configurations should use AUTOMEM_API_URL.

Note: Do not use shared/public AutoMem URLs. Deploy your own instance for production use.

Print Config Snippets

Re-print configuration snippets anytime:

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

MCP Tools

Memory Management

`store_memory`

Store a new memory with optional metadata.

Parameters:

content (required): Memory content - be specific, include context, reasoning, and outcome
type (optional): Memory classification (Decision, Pattern, Preference, Style, Habit, Insight, Context)
tags (optional): Array of bare tags for categorization (e.g., ["my-project", "bugfix", "auth"])
importance (optional): Score 0-1 (0.9+ critical, 0.7-0.9 patterns/bugs, 0.5-0.7 minor notes)
confidence (optional): How certain the memory is stable/correct (0.95 user-stated, ~0.8 observed, ~0.6 tentative)
metadata (optional): Structured metadata (e.g., { files_modified: ["auth.ts"], error_type: "timeout" })
embedding (optional): Vector for semantic search (auto-generated if omitted)
timestamp (optional): ISO timestamp (defaults to now)
t_valid / t_invalid (optional): Temporal validity window for facts with a shelf life

Example:

store_memory({
  content:
    "Chose PostgreSQL over MongoDB for user service. Need ACID for transactions.",
  type: "Decision",
  tags: ["decision", "my-project", "database"],
  importance: 0.9,
  confidence: 0.9,
});

`recall_memory`

Retrieve memories using hybrid search with semantic, keyword, tag, time, and graph expansion.

Basic Parameters:

query (optional): Natural language search query
queries (optional): Multiple queries for genuinely multi-topic recall; prefer one good query for focused tasks
limit (optional): Max results (default: 5, max: 50)
tags (optional): Hard tag filter (e.g., ["preference"] or ["my-project"])
tag_mode (optional): any (default) or all
tag_match (optional): exact or prefix (prefix supports namespaces)
state_mode (optional): current or history; use history for audits that need superseded/invalidated memories
recency_bias (optional): auto, on, or off
min_score (optional): Minimum final score threshold
adaptive_floor (optional): Let the service apply an adaptive score floor
scope_fallback (optional): Allow outside-tag fallback when scoped recall has weak evidence; fallback results are marked outside_tag_scope

Time Filters:

time_query (optional): Natural language time window (today, yesterday, last week, last 90 days)
start (optional): ISO timestamp lower bound
end (optional): ISO timestamp upper bound

Graph Expansion (Advanced):

expand_entities (optional): Enable multi-hop reasoning via entity expansion. Finds memories about people/places mentioned in seed results. Use for complex questions like "What is Sarah's sister's job?"
expand_relations (optional): Follow graph relationships from seed results to find connected memories.
expand_respect_tags (optional): Keep graph/entity expansion inside the original tag scope when true; leave false or drop tags when broader graph context is intended.
auto_decompose (optional): Auto-extract entities and topics from query to generate supplementary searches. Prefer false for focused recalls; use only for genuinely multi-topic requests.
expansion_limit (optional): Max total expanded memories (default: 25)
relation_limit (optional): Max relations per seed memory (default: 5)
expand_min_importance (optional): Minimum importance score (0-1) for expanded results. Use to filter out low-relevance memories during expansion (default: no filter)
expand_min_strength (optional): Minimum relation strength (0-1) to follow during expansion. Only follow strong associations (default: no filter)

Context Hints (Advanced):

context (optional): Context label (e.g., "coding-style", "architecture") - boosts matching preferences
language (optional): Programming language hint (e.g., "python", "typescript") - prioritizes language-specific memories
active_path (optional): Current file path for language auto-detection (e.g., "src/auth.ts")
context_tags (optional): Priority tags to boost in results (e.g., ["coding-style", "preferences"])
context_types (optional): Priority memory types to boost (e.g., ["Style", "Preference"])
priority_ids (optional): Specific memory IDs to ensure are included in results

Diagnostics:

Ranked recall preserves service diagnostics in structured output when present: state_mode, tag_scope, scope_fallback, recency_bias, score_filter, queries, query_time_ms, vector_search, jit_enriched_count, entities, and per-result outside_tag_scope, deduped_from, state_replaces, and enrichment/provenance flags.

Examples:

Preference recall:

recall_memory({
  tags: ["preference"],
  limit: 20,
  sort: "updated_desc",
  format: "detailed",
});

Semantic task recall:

recall_memory({
  query: "database architecture decisions PostgreSQL auth service",
  tags: ["my-project"],   // drop if the slug is ambiguous
  time_query: "last 90 days",
  limit: 30,
  format: "detailed",
});

Debug recall:

recall_memory({
  query: "TimeoutError authentication request timed out",
  tags: ["bugfix", "solution"],
  limit: 20,
});

Multi-hop reasoning (new!):

// "What is Amanda's sister's career?"
// Step 1: Finds "Amanda's sister is Rachel"
// Step 2: Expands to find "Rachel works as a counselor"
recall_memory({
  query: "What is Amanda's sister's career?",
  expand_entities: true,
});

Context-aware recall:

recall_memory({
  query: "error handling",
  language: "python",
  context: "coding-style",
  context_types: ["Style", "Preference"],
});

`associate_memories`

Create relationships between memories to build a knowledge graph.

Single Mode Parameters:

memory1_id (required): Source memory ID (from store_memory response or recall results)
memory2_id (required): Target memory ID to link to
type (required): Relationship type (see below)
strength (required): Association strength 0-1 (0.9+ direct causation, 0.7-0.9 strong, 0.5-0.7 moderate)
Relation-specific optional props: reason, context, resolution, observations, transformation, role, pattern_type, confidence, timestamp

Batch Mode:

associations (required): Array of up to 500 association objects with memory1_id, memory2_id, type, strength, and the same relation-specific optional props.
Batch responses include created_count, failed_count, succeeded, failed, and summary. Partial service responses are surfaced instead of thrown away.

Relationship Types:

RELATES_TO - General connection (default)
LEADS_TO - Causal relationship (A caused B)
DERIVED_FROM - Implementation of a decision/pattern
EXEMPLIFIES - Concrete example of a pattern
EVOLVED_INTO - Updated version of a concept
INVALIDATED_BY - Superseded by another memory
CONTRADICTS - Conflicts with another memory
REINFORCES - Strengthens another memory's validity
PART_OF - Component of a larger effort
PREFERS_OVER - Chosen alternative
OCCURRED_BEFORE - Temporal ordering

Internal/system relations such as SIMILAR_TO, PRECEDED_BY, EXPLAINS, SHARES_THEME, PARALLEL_CONTEXT, and DISCOVERED may appear in backend reads, but they are not valid values for associate_memories.

Example:

// Link a bug fix to the original feature it relates to
associate_memories({
  memory1_id: "bug-fix-123",
  memory2_id: "feature-456",
  type: "RELATES_TO",
  strength: 0.9,
});

associate_memories({
  associations: [
    {
      memory1_id: "new-decision",
      memory2_id: "old-decision",
      type: "INVALIDATED_BY",
      strength: 0.9,
      reason: "Superseded by the 0.15 release plan",
    },
  ],
});

`update_memory`

Update existing memory fields. Use this to correct or enhance memories rather than storing duplicates.

Parameters:

memory_id (required): Memory to update (from store_memory or recall results)
content (optional): New content (replaces existing)
tags (optional): New tags (replaces existing)
importance (optional): New importance score
metadata (optional): New metadata (merged with existing)
type (optional): Memory type classification
confidence (optional): Confidence score

Example:

update_memory({
  memory_id: "abc123",
  importance: 0.95,
  tags: ["project-x", "critical", "auth"],
});

`delete_memory`

Delete one memory by ID or bulk-delete all memories with any exact tag match. Use sparingly—consider updating instead.

Parameters:

memory_id (single mode): Memory to delete
tags (bulk-by-tag mode): Deletes all memories matching ANY tag exactly, case-insensitive. No dry-run; verify first with recall_memory({ tags, exhaustive: true }).

When to use:

Memory contains incorrect information that can't be corrected
Memory is a duplicate
Cleanup of test/benchmark data under a verified tag

System Monitoring

`check_database_health`

Check AutoMem service and database status (FalkorDB graph + Qdrant vectors). The status can be healthy, degraded, or error; structured output preserves sync counts, vector dimensions, and enrichment diagnostics when the service provides them.

Example:

Check the health of the AutoMem service

Additional Commands

Uninstall

Remove AutoMem configuration:

# Uninstall Cursor setup
npx @verygoodplugins/mcp-automem uninstall cursor

# Uninstall Claude Code setup
npx @verygoodplugins/mcp-automem uninstall claude-code

# Uninstall Hermes setup
npx @verygoodplugins/mcp-automem uninstall hermes

# Uninstall Grok Build setup
npx @verygoodplugins/mcp-automem uninstall grok

# Also clean Claude Desktop config
npx @verygoodplugins/mcp-automem uninstall cursor --clean-all

# Preview what would be removed
npx @verygoodplugins/mcp-automem uninstall cursor --dry-run

Help

View all available commands:

npx @verygoodplugins/mcp-automem help

Troubleshooting

Connection Issues

Service unreachable

Verify AUTOMEM_API_URL is correct and accessible
Check if AutoMem service is running (/health endpoint should return 200)
Ensure no firewall blocking the connection

Authentication errors

Check if AUTOMEM_API_KEY is required and properly set
Verify API key has appropriate permissions

Memory Issues

No memories returned

Verify memories exist in database
Check query parameters and filters
Ensure embeddings are generated if using semantic search

Storage failures

Check FalkorDB and Qdrant connections via health endpoint
Verify content doesn't exceed size limits
Ensure proper data formatting

Rules File Issues

"does not contain exactly one … block"

Every host writes its memory rules as a marked block ( … ) inside a Markdown file you also own. The installer rewrites only the bytes between those markers, so it requires exactly one correctly ordered pair.

If a rules file ends up with a stray marker — an interrupted run, a hand edit that removed half the block, or a merge that duplicated it — the installer refuses to touch the file and names the defect instead. Rewriting anyway would delete whatever sits between the stray markers, which is usually content you wrote.

Fix: open the file named in the error, remove or restore the stray marker so exactly one BEGIN/END pair remains (or delete the block entirely and let the installer re-add it), then re-run. Nothing was written, so nothing needs undoing. Hosts that only remove a stale block (OpenClaw's legacy AGENTS.md cleanup, Copilot's --format vscode re-run) print a warning and leave the file alone rather than failing the install.

Platform-Specific Issues

Claude Desktop: MCP server not appearing

Restart Claude Desktop completely
Check config file syntax (valid JSON)
Verify file path is correct for your OS

Cursor: Rules not applying

Reload Cursor window
Check .cursor/rules/ files have correct YAML frontmatter

Claude Code: Permissions not working

Check ~/.claude/settings.json has the MCP permissions
Verify MCP server is configured in ~/.claude.json
Run setup again: npx @verygoodplugins/mcp-automem claude-code

Claude Code: Hooks firing twice or storing duplicate/session-summary memories

Run setup again: npx @verygoodplugins/mcp-automem claude-code — the merge self-repairs duplicate hook registrations and removes retired hooks (the session-memory.sh Stop entry, the capture-*.sh PostToolUse hooks, and the queue-cleanup.sh + mcp-automem queue drainer Stop entries) along with their orphaned script files
A backup of settings.json is created automatically before any change
Preview first with --dry-run if you want to see what would change

Codex: MCP server not loading

Verify config file exists at ~/.codex/config.toml
Check TOML syntax is valid (no missing brackets or quotes)
Ensure command path is correct (use which npx or which node)
Check AutoMem endpoint is accessible: curl $AUTOMEM_API_URL/health
Restart Codex CLI or reload IDE extension
Ensure you have ChatGPT Plus/Pro/Team/Enterprise subscription

Codex: Memory tools not available

Verify [mcp_servers.memory] section exists in config.toml
Test explicitly: "Check AutoMem database health"
Check Codex logs for MCP connection errors
Ensure environment variables are set correctly in [mcp_servers.memory.env] section

Hermes: Tool names must be unique

Run npx @verygoodplugins/mcp-automem uninstall hermes --dry-run to see stale AutoMem surfaces.
Remove the stale setup with npx @verygoodplugins/mcp-automem uninstall hermes.
Reinstall one mode, usually npx @verygoodplugins/mcp-automem hermes --mode mcp.
If using --mode both, verify $HERMES_HOME/.env has AUTOMEM_HERMES_PROVIDER_TOOLS=false.
Check config.yaml for stale AutoMem-owned mcp_servers.memory; non-AutoMem memory servers are preserved by the uninstaller.

Copilot CLI / VS Code: SessionStart hook not injecting context

AutoMem's sessionStart hook outputs JSON via stdout ({"additionalContext":"..."}). If your PowerShell profile prints anything to the console during load -- Write-Output, Write-Host, Import-Module warnings, Invoke-Expression output, etc. -- that text appears before the JSON and corrupts the payload. The CLI silently fails to parse it, so the memory recall context never gets injected.

Symptoms:

AutoMem recall doesn't run automatically at session start
Hook script works when tested manually but not in practice
No visible error (the hook "succeeds" but its output is ignored)

Fix: Copilot CLI runs "powershell" values inside pwsh automatically - you should not invoke powershell or pwsh yourself. The "powershell" value should be raw PowerShell code (e.g. & "$HOME\.copilot\scripts\script.ps1").

If you've installed hooks from an older version that invoked the shell directly, update your ~/.copilot/hooks/*.json files:

- "powershell": "powershell -NoProfile -ExecutionPolicy Bypass -File \"$HOME/.copilot/scripts/automem-session-start.ps1\""
+ "powershell": "& \"$HOME\\.copilot\\scripts\\automem-session-start.ps1\""

Or re-run the installer to get the updated hook configs:

npx @verygoodplugins/mcp-automem copilot --yes

Development

Building from Source

npm install
npm run build

Development Mode

npm run dev  # Watch mode with auto-reload

Testing

npm test

Support

MCP Client (this repo)

Issues: GitHub Issues - MCP client bugs, platform integrations
Documentation: This guide - MCP setup for all platforms

AutoMem Service (backend)

Service Documentation: AutoMem Installation Guide - Service deployment, Railway setup
Service Issues: AutoMem Issues - Backend bugs, API questions
Repository: AutoMem Service - Backend source code

Credits

Built by Jack Arturo 🧡

Powered by AutoMem
Built with Model Context Protocol
Part of the Very Good Plugins ecosystem

FilesExpand file tree

INSTALLATION.md

Latest commit

History

INSTALLATION.md

File metadata and controls

Installation Guide

Prerequisites

Quick Start

Guided install (fastest)

Manual setup

AutoMem Service Setup

Option 1: Local Development (Recommended for Getting Started)

Option 2: Railway Cloud (Recommended for Production)

Option 3: Self-Hosted Production

MCP Client Setup

Remote MCP via HTTP (Sidecar)

When to use the remote MCP sidecar

Deploy the remote MCP sidecar

Configure platforms

ChatGPT (Developer Mode)

Claude.ai (Web)

Claude Mobile (iOS/Android)

ElevenLabs Agents

Troubleshooting (Remote MCP)

Guided Setup Wizard

Claude Desktop

1. Install MCP Server

2. Restart Claude Desktop

3. Verify Installation

4. Add Personal Preferences (Optional but Recommended)

Cursor IDE

1. One-Click Install (Fastest)

2. Add Memory Rule (Recommended)

3. How Cursor Loads Instructions

4. Global User Rules (Optional)

Claude Code

Option A: Plugin (Recommended)

Option B: CLI installer (settings-level)

1. Configure MCP Server

2. Install hooks and permissions

Add Memory Rules (both options)

Verify Installation

Tool search and deferred loading

GitHub Copilot coding agent (GitHub.com)

Plans and availability

1. Create a Copilot environment secret (recommended)

2. Add the MCP configuration to your repository

Optional: organization/enterprise-level setup (custom agents)

Optional: connect via remote MCP (HTTP/SSE “bridge”)

GitHub Copilot CLI and VS Code

1. Configure MCP Server

2. Install Hooks and Memory Rules

3. Verify Installation

4. Uninstall

OpenAI Codex

1. Install Codex CLI

2. Authenticate

3. Configure MCP Server

3.5. Add Memory Rules (Optional but recommended)

4. Restart Codex

5. Verify Installation

How to Use with Codex

Memory Best Practices for Codex

Integration with GitHub

Cross-Platform Memory Sync

Hermes Agent

1. Choose an install mode

2. Verify

3. See what recall injects

4. Uninstall

Troubleshooting

Grok Build

Install

Verify

Uninstall

Troubleshooting

Google Antigravity

1. Open Antigravity's MCP raw config

2. Add the AutoMem MCP server

`store_memory`

`recall_memory`

`associate_memories`

`update_memory`

`delete_memory`

`check_database_health`