agentmemory
Local persistent memory for coding agents: hooks record every session, and Claude Code, Codex or Cursor recall past decisions through 54 MCP tools
Medium risk
We rate an entry medium when the tool runs code, makes network calls or reads project files. Check what exactly it does before installing.
Why this level
- Hooks store your prompts, tool calls and their output in a local database; the filter strips only keys, secrets and <private> tags
- The REST API on port 3111 listens on localhost and answers without a password unless AGENTMEMORY_SECRET is set
- If LLM compression is on, observations are sent to the chosen provider's external API
Install
Manual install
npx -y @agentmemory/agentmemory@latestStarts the memory server and the setup wizard: pick agents and a provider or stay keyless. Keep it running in a separate terminal. To wire another agent: npx -y @agentmemory/agentmemory@latest connect <agent>.
Security check
How we reviewMedium riskWe rate an entry medium when the tool runs code, makes network calls or reads project files. Check what exactly it does before installing.
- Hooks store your prompts, tool calls and their output in a local database; the filter strips only keys, secrets and <private> tags
- The REST API on port 3111 listens on localhost and answers without a password unless AGENTMEMORY_SECRET is set
- If LLM compression is on, observations are sent to the chosen provider's external API
This is third-party code. Review the repository files before installing.
What it does
agentmemory runs a memory server on your machine and connects your agent to it through an MCP server, hooks and skills. The hooks record prompts, tool calls, errors and session summaries. Before anything is stored, a filter strips API keys, secrets and text inside <private> tags. The agent gets 54 tools: save a decision, find it with hybrid BM25, vector and knowledge graph search, look up a file's history or past sessions, and hand context over to another agent. Without keys, search runs on BM25; local all-MiniLM-L6-v2 embeddings turn on with EMBEDDING_PROVIDER=local in ~/.agentmemory/.env, and a web viewer on port 3113 shows what has been stored.
Who it is for. For developers who work on a project in Claude Code, Codex, Cursor or several agents at once and keep re-explaining the architecture and conventions every session.
Good fit when
- Your agent re-learns the project and asks about past decisions in every new session
- Several agents, such as Claude Code and Codex, work on one project and need shared memory
- You need to find when and why a specific file was changed or a similar bug was fixed
- CLAUDE.md has grown large and the agent spends context on it every session
Not a fit when
- Short one-off tasks where past session history will not help
- Company policy forbids storing prompts and tool output on disk, even locally
- You cannot run a background server or use ports 3111–3113 and 49134 on the machine
Example request
Check memory for how we set up auth last week and why we picked jose, then add rate limiting in the same styleMCP
- Transport
- stdio
- Authentication
- not required
Environment variables
AGENTMEMORY_URL- URL of the running agentmemory server, http://localhost:3111 by default
AGENTMEMORY_SECRETsecret- Bearer token, needed when the server protects its REST API
EMBEDDING_PROVIDER- Set to local for on-device embeddings and semantic search, configured in ~/.agentmemory/.env
AGENTMEMORY_INJECT_CONTEXT- Set to true to inject recalled memory into context at session start; spends tokens
Limitations
Requires Node.js 20 or newer, plus curl, sh and tar on macOS and Linux, since the installer downloads iii-engine v0.22.1 itself. On Windows the engine is installed manually or run through WSL2 or Docker Desktop, and connect only wires GitHub Copilot CLI automatically there. The server has to run separately; without it the @agentmemory/mcp package exposes 7 of the 54 tools. Vector search is off by default, and the local model downloads on first use. LLM compression of observations and automatic context injection are off because they spend tokens; compression needs an Anthropic, OpenAI, Gemini or OpenRouter key, or a local model through Ollama. The server itself needs no VPN from Russia, while the Anthropic and OpenAI APIs do.
How to disable. agentmemory stop shuts the server down, and agentmemory remove deletes everything the installer created; with Docker use agentmemory remove --keep-data. In Claude Code remove the plugin with /plugin uninstall agentmemory@agentmemory, and in other agents delete the agentmemory block from the MCP config.
FAQ
Do I need an API key?
No. Without keys agentmemory searches with BM25, and embeddings can run locally with EMBEDDING_PROVIDER=local. A provider key is only needed for LLM compression of observations.
How is this different from CLAUDE.md?
CLAUDE.md is loaded into context in full every session. agentmemory keeps observations in a database, returns only the fragments a query finds and can sync with MEMORY.md in Claude Code.
Why does my agent see only 7 tools?
The @agentmemory/mcp package could not reach the server. Start npx -y @agentmemory/agentmemory@latest, make sure AGENTMEMORY_URL points to http://localhost:3111 and reload MCP in the agent.
Related
MCP serversOpen-source personal AI assistant on your own machine: answers in Telegram, Slack, Discord and WhatsApp, extended with skills and plugins
A self-improving agent from Nous Research with a TUI, messaging gateway, cron jobs and skills it writes itself
An open source coding agent for the terminal and desktop with build and plan modes
Open prompt library with a Claude Code plugin, MCP server and CLI: search, fetch and improve prompts and skills from an agent
README in short
The README opens with a single npx install and an interactive setup where you pick agents and a model provider or stay keyless. It goes on to the author's LongMemEval-S and in-house session benchmarks, a comparison with mem0, Letta and built-in agent memory, and a diagram of the four-tier memory pipeline. Separate sections cover the 20 connect adapters, plugins for Claude Code, Codex and Copilot CLI, all 54 MCP tools, the REST API, environment variables and running on Windows. The README has a Russian translation, and agents get a dedicated INSTALL_FOR_AGENTS.md runbook.
README badge
Are you the author? Show in your README that the project is reviewed in the SkillFoxx catalog. The badge updates itself.
[](https://skillfoxx.ru/mcp/agentmemory?utm_source=github&utm_medium=badge&utm_campaign=readme)