# 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`**

```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.**

```json
{
  "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`:

```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`:

```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:

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

Or use the CLI:

```bash
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):

```json
{
  "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](https://www.npmjs.com/package/@agent-memo/mcp-client)
- Dashboard: https://agent-memo.ai/dashboard
- Full documentation: https://agent-memo.ai/docs/setup