tverney/mcp-agent-memory

MCP server that exposes agent-memory-daemon to any MCP-compatible client — **Kiro (CLI & IDE), Claude Desktop, Cursor**, and others.
The daemon does the thinking (consolidation + extraction); this server is a thin filesystem bridge so agents can **read**, **append**, and **search** memory through the Model Context Protocol.
How it fits together
- The **MCP server** reads/writes files under ~/.agent-memory/
- The **daemon** watches the same directory and runs consolidation + extraction passes
- They never talk to each other directly — the filesystem is the contract
Tools exposed
memory_read
Read the agent memory index (MEMORY.md) and optionally specific topic files. Call with no arguments to load only the lightweight index (cheap). Pass topics only when you need the full content of a specific topic file.
| Parameter | Type | Required | Description |
|---|---|---|---|
| topics | string[] | No | Topic file names to load in full (e.g., ["preferences", "projects"]). Omit to return the index only. |
memory_append_session
Append a session summary to the sessions directory. The daemon will later extract durable memories from it. Call this at the end of meaningful exchanges. Keep summaries focused on durable findings and decisions (target 300–800 tokens), not play-by-play — longer summaries cost more during consolidation.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content | string | Yes | Markdown-formatted session summary. Use structured headers and bullets for better extraction; avoid verbose prose. |
| source | string | No | Origin tag, e.g., "kiro", "claude-desktop" |
memory_search
Search memory files for a substring. Use this to recall specific facts without loading everything.
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | The substring to search for across all memory files. |
Install
Quick start (interactive wizard)
The fastest way to set everything up — memory directory, daemon, client configs, logs, and auto-start service (macOS LaunchAgent or Linux systemd user service) — is the setup wizard:
It asks six questions:
1. **Memory directory** — where .agent-memory/ lives (default ~/.agent-memory)
2. **Install the consolidation daemon?** — say "no" for MCP-only mode (agents can read/write/search memory, but no automatic consolidation)
3. **LLM backend** — bedrock, openai, or kiro (skipped if you declined the daemon)
4. **Consolidation settings** — min_hours, min_sessions, extraction interval, max chars
5. **Run mode** — standalone (start manually), launchagent (auto-start at login, macOS), or systemd (systemd user service, Linux). On Linux the wizard only offers systemd if systemctl --user is reachable; otherwise it falls back to standalone and tells you why.
6. **Logs directory + TTL** — where to put logs, and how many days to keep them (0 = forever)
7. **Client registration** — auto-register the MCP server in Kiro, Claude Desktop, and/or Cursor configs (existing MCP entries are preserved)
When you select the kiro backend, the wizard also copies a lean agent to ~/.kiro/agents/memconsolidate.json that cuts token usage by ~7× (see Kiro backend).
When you select launchagent or systemd, the wizard checks that agent-memory-daemon is installed (and offers to npm install -g it if not), then registers and starts the plist / user unit.
CLI reference
--remove preserves other entries in client MCP configs — only the memory key is deleted. By default it backs up ~/.agent-memory/ to a timestamped .bak-* directory so you can restore your consolidated memories.