Skip to main content
By the end of this quickstart, you will have Agent Memory installed, the memory server running on your machine, your agent connected via MCP, and persistent recall verified with a live demo. The whole process takes under 2 minutes on a machine with Node.js already installed.
1
Install Agent Memory globally
2
Install the agentmemory CLI globally so the bare command is available everywhere on your PATH:
3
npm install -g @agentmemory/agentmemory
4
If you hit an EACCES permission error on macOS or Linux with a system Node install, retry with sudo npm install -g @agentmemory/agentmemory.
5
If you prefer not to install globally, you can use npx for every command instead. Add -y and @latest to always get the newest version:
6
npx -y @agentmemory/agentmemory@latest
7
A bare npx @agentmemory/agentmemory without @latest may serve a cached older version from ~/.npm/_npx/. Always use @latest with npx, or install globally to avoid stale releases.
8
Initialize your config
9
Run agentmemory init to create the config directory and drop a template .env file into place:
10
agentmemory init
11
This creates ~/.agentmemory/.env with every available setting commented out. You do not need to edit this file to get started — Agent Memory runs in zero-LLM mode out of the box.
12
(Optional) Add an LLM API key
13
Open ~/.agentmemory/.env in any editor and uncomment one provider key. Agent Memory auto-detects which key is present:
14
# ~/.agentmemory/.env

# Pick one:
ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=sk-...
# GEMINI_API_KEY=...
# OPENROUTER_API_KEY=sk-or-...
15
No key required. Without an LLM key, Agent Memory still captures observations, indexes them via BM25 keyword search, and recalls context using local embeddings (all-MiniLM-L6-v2 runs on-device). You only miss LLM-backed summarization and knowledge graph extraction. Most users get valuable recall without a key.
16
To use a local model (Ollama, LM Studio, vLLM) instead of a cloud API, set:
17
# ~/.agentmemory/.env  — Ollama example
OPENAI_API_KEY=ollama
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen2.5-coder:7b
18
Start the memory server
19
Start Agent Memory in a dedicated terminal (or background it with &):
20
agentmemory
21
The server starts two services:
22
  • REST API + MCP server on port 3111 — this is what your agent talks to
  • Real-time viewer on port 3113 — open http://localhost:3113 in your browser to watch memories build live
    • 23
    On the first run, Agent Memory downloads and pins the iii engine binary into ~/.agentmemory/bin. This takes a few seconds and only happens once. You will see a health confirmation when the server is ready:
    24
    agentmemory v0.9.x ready
  REST API  →  http://localhost:3111
  Viewer    →  http://localhost:3113
  Tools     →  53 MCP tools available
    25
    Verify the server is up at any time:
    26
    curl http://localhost:3111/agentmemory/health
    27
    Connect your agent
    28
    Use the agentmemory connect CLI command to wire Agent Memory into your agent’s MCP config automatically. The command merges the MCP server entry into your agent’s config file without overwriting any existing servers.
    29
    Claude Code
    agentmemory connect claude-code
    Or use the Claude Code plugin marketplace for the full experience (hooks + skills + MCP in one step):
    /plugin marketplace add rohitg00/agentmemory
/plugin install agentmemory
    The plugin registers all 12 auto-capture hooks, 15 skills, and the MCP server in one command.
    Cursor
    agentmemory connect cursor
    This merges the MCP config into ~/.cursor/mcp.json. Restart Cursor after running the command.
    Other agents
    Replace <agent> with your agent name:
    agentmemory connect <agent>
    Supported agents: claude-code, cursor, copilot-cli, codex, gemini-cli, cline, zed, warp, continue, openclaw, hermes, pi, openhuman, droid, kiro, qwen, antigravitySee Connect Agents for per-agent instructions.
    30
    After connecting, restart your agent (or run its MCP reload command, e.g. /mcp in Claude Code) so it picks up the new server. You should see memory_save, memory_smart_search, memory_sessions, and other tools listed.
    31
    Check server status
    32
    Run agentmemory status to confirm the server is running and your agent is registered:
    33
    agentmemory status
    34
    You will see output similar to this:
    35
    ● agentmemory  running  (pid 12345)
  Version      0.9.x
  Uptime       2m 14s
  REST API     http://localhost:3111  ✓ reachable
  Viewer       http://localhost:3113  ✓ reachable

  Memory
    Sessions   3 sessions captured
    Memories   47 memories stored
    Tokens     ~1,840 tokens/session (est.)

  Connected agents
    claude-code  ✓ wired  (MCP + 12 hooks)
    36
    If the server is not reachable, or tools are not showing up in your agent, run agentmemory doctor — it checks your full setup and suggests fixes.
    37
    Run the demo to verify recall
    38
    Seed three realistic sessions and prove that semantic recall actually works:
    39
    agentmemory demo
    40
    The demo seeds three real-world coding sessions — JWT authentication setup, an N+1 database query fix, and rate limiting middleware — then runs semantic searches against them. Watch it find the “N+1 query fix” session when you search for "database performance optimization". Keyword matching cannot make that connection. Semantic search can.
    41
    If you want to run the demo without having the server already running in another terminal, use --serve:
    42
    agentmemory demo --serve
    43
    This boots the server, runs the full demo, and tears everything down in a single command.
    44
    Open http://localhost:3113 while the demo runs to watch the memory viewer populate in real time.

    ​
    What happens next

    From this point on, Agent Memory works automatically in the background. Every time your agent reads a file, runs a command, writes code, or hits an error, Agent Memory captures that as an observation. At the end of each session, it compresses those observations into searchable memories. At the start of the next session, it injects the most relevant context so your agent already knows your project. You do not need to change how you work.

    ​
    Other useful commands

    Once the server is running, you have a few more commands at your disposal: 
    agentmemory stop       # Stop the running memory server and iii-engine
agentmemory remove     # Cleanly uninstall Agent Memory (pidfile, state, .env, binaries)
agentmemory upgrade    # Upgrade Agent Memory and the iii runtime to the latest release
    Use agentmemory stop when you want to pause memory capture and free up ports. Use agentmemory remove if you ever want to start fresh — it prompts for confirmation before deleting anything. Use agentmemory upgrade to pull the latest release without reinstalling manually.
    Troubleshooting: Run agentmemory doctor at any time for interactive diagnostics. It checks the server, engine, MCP wiring, port availability, and your config file, then suggests specific fixes. It is the fastest path to resolving any setup issue.
    For a complete list of supported agents and per-agent wiring details, see Connect Agents.