Set up Agent-Memo with an AI agent

Agent-Memo.AI Setup Guide

Give this document to your AI agent (Claude Code, Cursor, Windsurf, etc.) and it will configure Agent-Memo automatically.

What is Agent-Memo?

Agent-Memo.AI is a cloud memory service for AI coding agents. It gives you persistent memory across sessions — decisions, architecture choices, user preferences, and project context are stored and recalled automatically.

Prerequisites

• A free API token from https://agent-memo.ai (sign up → dashboard → copy token)
• Node.js 18+ (for npx)

Setup Instructions

Step 1: Detect your agent

Determine which AI agent is running and follow the corresponding config below.

---

Claude Code

Create two files in the project root:

File 1: .mcp.json

{
  "mcpServers": {
    "agent-memo": {
      "command": "npx",
      "args": ["-y", "@agent-memo/mcp-client"],
      "env": {
        "AGENTMEMO_TOKEN": "YOUR_TOKEN",
        "AGENTMEMO_PROJECT": "YOUR_PROJECT"
      }
    }
  }
}

File 2: .claude/settings.local.json

This configures hooks for automatic memory management. Required for full automation.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "npx -y @agent-memo/mcp-client --hook recall",
            "timeout": 30
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "npx -y @agent-memo/mcp-client --hook save",
            "timeout": 30
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx -y @agent-memo/mcp-client --hook precompact",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

What the hooks do:

• SessionStart: Recalls important memories when a new session begins.
• Stop: Periodically saves important context (every 15 stops).
• PreCompact: Saves critical info before context window compression.

---

Cursor

Create one file at .cursor/mcp.json:

{
  "mcpServers": {
    "agent-memo": {
      "command": "npx",
      "args": ["-y", "@agent-memo/mcp-client"],
      "env": {
        "AGENTMEMO_TOKEN": "YOUR_TOKEN",
        "AGENTMEMO_PROJECT": "YOUR_PROJECT"
      }
    }
  }
}

You can also configure via Cursor Settings → MCP.

Cursor does not support hooks. Add instructions to your .cursorrules file to call memory_overview() at session start and memory_store() for important decisions.

---

Windsurf

Add to your global config at ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "agent-memo": {
      "command": "npx",
      "args": ["-y", "@agent-memo/mcp-client"],
      "env": {
        "AGENTMEMO_TOKEN": "YOUR_TOKEN",
        "AGENTMEMO_PROJECT": "YOUR_PROJECT"
      }
    }
  }
}

You can also configure via Windsurf Settings → MCP.

Windsurf does not support hooks. Add instructions to your .windsurfrules file to call memory_overview() at session start and memory_store() for important decisions.

---

OpenClaw

Add to your config at ~/.openclaw/openclaw.json under the mcpServers key:

{
  "mcpServers": {
    "agent-memo": {
      "command": "npx",
      "args": ["-y", "@agent-memo/mcp-client"],
      "env": {
        "AGENTMEMO_TOKEN": "YOUR_TOKEN",
        "AGENTMEMO_PROJECT": "YOUR_PROJECT"
      }
    }
  }
}

Or use the CLI:

openclaw mcp set agent-memo '{"command":"npx","args":["-y","@agent-memo/mcp-client"],"env":{"AGENTMEMO_TOKEN":"YOUR_TOKEN","AGENTMEMO_PROJECT":"YOUR_PROJECT"}}'

The Gateway watches the config file and applies changes automatically — no restart needed.

OpenClaw does not support hooks. Add instructions to your AGENTS.md to call memory_overview() at session start and memory_store() for important decisions. You can also use per-agent MCP routing under agents.<agent-name>.mcpServers to control which agents access Agent-Memo.

---

Other MCP-Compatible Agents

Create .mcp.json in the project root (or check your agent's docs for the config file location):

{
  "mcpServers": {
    "agent-memo": {
      "command": "npx",
      "args": ["-y", "@agent-memo/mcp-client"],
      "env": {
        "AGENTMEMO_TOKEN": "YOUR_TOKEN",
        "AGENTMEMO_PROJECT": "YOUR_PROJECT"
      }
    }
  }
}

If your agent does not support hooks, add instructions to your agent's instruction file to call memory_overview() at session start and memory_store() for important decisions.

---

Environment Variables

Variable	Required	Description
AGENTMEMO_TOKEN	Yes	Your API token from the dashboard
AGENTMEMO_PROJECT	No	Project identifier. If omitted, auto-detected from git remote URL or directory name

Available MCP Tools (14)

Once configured, the agent has access to these tools:

Memory (7): memory_store, memory_recall, memory_overview, memory_expand, memory_update, memory_delete, memory_stats

Discovery (2): memory_list_topics, memory_check_duplicate

Knowledge Graph (5): kg_add, kg_query, kg_invalidate, kg_timeline, kg_stats

Verification

After setup, verify the connection by calling:

memory_stats()

This should return memory counts and confirm the connection is working.

Notes

• Memories are scoped per project by default. Projects are auto-detected from git remote URL or directory name.
• The token authenticates all API calls. Keep it private.
• NPM package: @agent-memo/mcp-client
• Dashboard: https://agent-memo.ai/dashboard
• Full documentation: https://agent-memo.ai/docs/setup