agentmemoryMCP Server

The problem it solves

Every new agent session starts from nothing. You re-explain the architecture, the conventions, the thing you tried last week that did not work. agentmemory records that context as you work and serves it back to whichever agent asks for it, so the knowledge outlives a single session and is shared between the tools you use rather than trapped in one.

How it works

A local memory server runs on your machine and exposes three interfaces: MCP, a REST API, and native hooks. Hooks are the part that makes it low-effort — the agent's own tool calls and interactions are captured automatically as you work, compressed into searchable observations, with no manual "remember this" step. Any agent that supports hooks, MCP or REST can attach, and they all share the same memory server, so a note captured while working in one editor is available in the next.

Retrieval is hybrid rather than embeddings-only: BM25 keyword search, vector similarity, and structural matches from a knowledge graph. That matters for the keyless default — with no API key configured, vector embeddings are off and recall runs on BM25 alone, which handles keyword queries but not semantic ones. Setting EMBEDDING_PROVIDER=local gives free on-device semantic search; the first request downloads the Xenova/all-MiniLM-L6-v2 model and inference is local from then on.

The project reports 95.2% retrieval accuracy (R@5) on the LongMemEval-S benchmark and 92% fewer tokens than passing full context, and ships a demo command that seeds sample sessions so you can check recall yourself.

Running it

Node.js 20 or newer. npx -y @agentmemory/agentmemory@latest is the canonical install and start command. The runtime uses four local ports — 3111 for REST and MCP over HTTP, 3112 for iii streams, 3113 for the viewer UI, and 49134 for the engine's WebSocket worker — and stores state in the platform data directory (~/Library/Application Support/agentmemory on macOS, $XDG_DATA_HOME/agentmemory on Linux, %APPDATA%\agentmemory on Windows), overridable with --data-dir.

One caveat worth knowing before you install: agentmemory pins iii-engine v0.11.2 and will not attach to a different version, so if you already run your own iii you need to stop it first. It installs the pinned engine under ~/.agentmemory/bin and leaves your copy alone.

Wiring it up

The MCP entry is identical across every host that uses the mcpServers config shape — Claude Desktop, Cursor, Cline, Roo Code, Gemini CLI and others — and points at the thin @agentmemory/mcp shim, which re-exposes the main package's MCP entrypoint and exposes 54 memory tools when the server is reachable (falling back to 7 core tools when it is not). AGENTMEMORY_URL defaults to http://localhost:3111, so the same entry covers both a local server and a remote or reverse-proxied deployment. Apache 2.0.