Complete Guide: Set Up Agent-Memo MCP for Claude Code (2026)

Step-by-step tutorial to give Claude Code persistent memory. From signup to first memory in 5 minutes. Covers MCP config, hooks, CLAUDE.md, and real usage examples.

TL;DR:Claude Code is powerful but forgets everything between sessions. This guide shows you exactly how to add persistent cloud memory using Agent-Memo — from signup to your first stored memory in under 5 minutes. Free tier included.

What you'll get

After following this guide, your Claude Code agent will:

Remember decisions, preferences, and project context across sessions
Automatically recall relevant memories when starting a new conversation
Auto-save important context periodically and before context compression
Build a knowledge graph of entity relationships in your project

No SDK integration, no code changes. Just two config files.

Prerequisites

Node.js 18+ installed (node -v to check)
Claude Code installed (CLI, VS Code extension, or desktop app)
5 minutes of your time

Step 1: Create your free account

Go to agent-memo.ai/registerand sign up. You'll get a free tier with:

3 projects
1,000 memories
1,000 API calls per month
100 knowledge graph facts

No credit card required.

Step 2: Get your API token

After logging in, go to Settings → API Keys and click Create New Key. Copy the token — you'll need it in the next step.

Your token looks like: eyJhbGciOiJIUzI1NiIs...

Step 3: Create .mcp.json

In your project root directory, create a file called .mcp.json:

{
  "mcpServers": {
    "agent-memo": {
      "command": "npx",
      "args": ["-y", "@agent-memo/mcp-client"],
      "env": {
        "AGENTMEMO_TOKEN": "paste-your-token-here"
      }
    }
  }
}

That's it for the MCP server. When Claude Code starts, it will launch the Agent-Memo MCP server and discover 14 memory tools automatically.

Want it globally? Instead of per-project .mcp.json, add it to ~/.claude/settings.json under "mcpServers" so every project gets persistent memory.

Step 4: Add auto-save hooks (recommended)

Hooks make memory management fully automatic. Create .claude/settings.local.json in your project root:

{
  "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
          }
        ]
      }
    ]
  }
}

Here's what each hook does:

SessionStart — Recalls your high-importance memories when Claude Code starts. Your agent immediately has context from previous sessions.
Stop — Every 15 user messages, pauses to save important information learned during the conversation.
PreCompact — When Claude's context window is about to be compressed, saves all critical context so nothing is lost.

Step 5: Add to CLAUDE.md (optional but powerful)

To make your agent use memory proactively, add these instructions to your project's CLAUDE.md file:

## Memory System

This project uses Agent-Memo cloud MCP for persistent memory.

**At the start of EVERY conversation:**
1. Call memory_overview() to load context
2. Check memories before asking the user to repeat information

**During conversation:**
- When you learn something important → memory_store() immediately
- When you need context → memory_recall(query)
- Before storing → memory_check_duplicate()
- After storing → Extract KG relationships with kg_add()

This tells Claude to use the memory tools actively instead of waiting for you to ask.

Step 6: Verify it works

Start Claude Code and you should see:

> claude
[SessionStart hook: recalling memories...]
Claude: I've loaded my memory context. How can I help you today?

Try storing a memory manually:

You: Remember that this project uses PostgreSQL with pgvector.
Claude: [calls memory_store()] ✓ Stored. I'll remember this
        across all future sessions.

Close the session, start a new one, and ask:

You: What database do we use?
Claude: [calls memory_recall("database")] This project uses
        PostgreSQL with pgvector, as noted in a previous session.

The 14 tools your agent now has

Agent-Memo gives your agent a complete memory toolkit:

Memory tools (7)

memory_store — Save a memory with type, importance (1-4), topic, and tags
memory_recall — Semantic search across all memories (powered by BGE-M3 multilingual embeddings)
memory_overview — Load a compact summary of your most important memories
memory_expand — Get full content of a specific memory and its children
memory_update — Modify an existing memory when facts change
memory_delete — Remove a memory that's no longer relevant
memory_stats — View memory counts by type and topic

Knowledge Graph tools (5)

kg_add — Record entity relationships (e.g., "ProjectX uses PostgreSQL")
kg_query — Find all relationships for an entity
kg_timeline — Track how relationships change over time
kg_invalidate — Mark a relationship as no longer valid
kg_stats — Graph statistics

Discovery tools (2)

memory_list_topics — See all topics in your project's memory
memory_check_duplicate — Avoid storing redundant information

Best practices

Always set a topic when storing memories (e.g., "database", "auth", "deployment"). This makes recall much more accurate.
Use importance levels wisely: 1 = nice to know, 2 = useful context (default), 3 = important decision, 4 = critical/never forget.
Store decisions, not facts the code already shows. "We chose PostgreSQL over MongoDB because of pgvector support" is a good memory. "The main file is index.ts" is not.
Extract KG relationships after storing memories. This builds a queryable graph of your project's architecture.
Let hooks do the work. You rarely need to manually tell the agent to store memories — the Stop hook handles periodic saves, and CLAUDE.md instructions handle the rest.

Memory types explained

Use these types to organize your memories:

user — Your preferences, role, skills, work style
project — Architecture decisions, tech choices, deployment info
feedback — Corrections you've given the agent ("don't use mocks in tests")
reference — Links to external resources, documentation, dashboards
conversation — Session summaries, handover notes

Works with other agents too

Agent-Memo isn't limited to Claude Code. The same .mcp.json configuration works with any MCP-compatible agent:

Cursor — Add .mcp.json to project root (no hooks support yet)
Windsurf — Same configuration as Cursor
OpenClaw — Add to MCP config in your OpenClaw setup
Any MCP client — Standard MCP protocol, universal compatibility

Troubleshooting

"AGENTMEMO_TOKEN not set" — Make sure your token is in the env section of .mcp.json, not in your system environment variables.
MCP server won't connect — Run npx @agent-memo/mcp-client manually to see errors. Most common: outdated Node.js (< 18).
Memories not being recalled — Check that the SessionStart hook is configured. Run npx @agent-memo/mcp-client --hook recall manually to test.
Too many memories / noise — Use topics and importance levels to keep memories organized. Low-importance memories won't appear in overview.

What's next?

Once you're set up:

Use the dashboard to browse your memories, view the knowledge graph, and manage API keys
Read about knowledge graphs to understand entity relationships
Check the REST API docs if you want to integrate memory into your own tools

Create your free account and give your agent a memory that lasts forever.