Agent Memory MCP Server

agent-memory-mcp

Markdown memory for AI agents. Your data is just files.

Markdown memory for AI agents. Plain files in a directory you control — read them, edit them, grep them, commit them. Operator-grade storage primitives (atomic writes, file locking, soft-delete to .trash/, schema versioning, doctor command) wrap the files so nothing rots in the long tail.

You can cat your memory. You can grep it. You can edit it in vim. You can commit it to git. You can move it between machines with scp or with the built-in agent-memory sync (git-backed). If the AI gets a memory wrong, you fix it in a text editor and save. No migration scripts. No vendor lock-in.

---

What you get

.agent-memory/
├── MEMORY.md                           # auto-managed index
├── user-prefers-tabs.md
├── feedback-no-emoji-in-code.md
├── project-q3-launch-frozen.md
└── reference-postgres-runbook.md

A memory file is just markdown with YAML frontmatter:

---
name: feedback-no-emoji-in-code
description: User wants zero emoji in commits, comments, or output
type: feedback
---

Hard rule. No emoji anywhere user-facing.

**Why:** prior contractor flooded the repo with them; user spent a
weekend removing them.

**How to apply:** scrub before commit; reject any tool output that
adds them automatically.

That's the whole format. No magic. Read it, edit it, ship it.

---

Why this exists

Most MCP clients have no persistent memory. The ones that do (Claude Code) store it where only that client can see it. The official server-memory and every community alternative use opaque structured backends. That's fine for some workflows — but it puts your data behind a layer you can't read with cat.

We chose markdown because:

• Universal. Every developer can read markdown. Every editor handles it. Every diff tool understands it.
• Portable. Memories travel with the project (per-project default) or with you (global mode). Move them, copy them, fork them — they're just files.
• Inspectable. You can audit what your AI assistant "knows" by opening a folder.
• Repairable. When a memory is wrong, you fix it the way you fix any text file. No SDK, no API, no SQL.
• Versionable. Git understands every change. No JSON merge conflicts. No binary blobs.

If you want vector similarity search, semantic recall, or auto-relation extraction — use one of the database-backed memory MCPs. They're great at that. If you want memory that you can still read after a power outage, this is for you.

---

Install

From npm (recommended)

npx -y @xultrax-web/agent-memory-mcp

Listed in the MCP Registry

io.github.xultrax-web/agent-memory-mcp · browse at https://registry.modelcontextprotocol.io

Build locally

git clone https://github.com/xultrax-web/agent-memory-mcp
cd agent-memory-mcp
npm install
npm run build
node dist/index.js

The server speaks MCP over stdio. You don't run it directly — your MCP client launches it.

---

Client configuration

Same JSON, slightly different paths per client.

Cursor

~/.cursor/mcp.json (or .cursor/mcp.json in your project):

{
  "mcpServers": {
    "agent-memory": {
      "command": "npx",
      "args": ["-y", "@xultrax-web/agent-memory-mcp"]
    }
  }
}

Cline (VS Code extension)

Cline → MCP Servers → Add:

{
  "agent-memory": {
    "command": "npx",
    "args": ["-y", "@xultrax-web/agent-memory-mcp"]
  }
}

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "agent-memory": {
      "command": "npx",
      "args": ["-y", "@xultrax-web/agent-memory-mcp"]
    }
  }
}

Windows note: if npx doesn't resolve cleanly, wrap with cmd /c:

{ "command": "cmd", "args": ["/c", "npx", "-y", "@xultrax-web/agent-memory-mcp"] }

Continue.dev

~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@xultrax-web/agent-memory-mcp"]
        }
      }
    ]
  }
}

Storage scope

Per-project (default): memories live in ./.agent-memory/ relative to wherever the client launched the server. Usually that's the project root.

Personal / global pool:

"env": { "AGENT_MEMORY_SCOPE": "global" }

Global memories live at ~/.agent-memory/.

Custom path:

"env": { "AGENT_MEMORY_DIR": "/abs/path/to/memory" }

---

Tools

Prompts

The server exposes 4 built-in MCP prompts that clients (Claude Desktop, Cursor, etc.) surface as slash-commands. These turn memory into an active workflow layer, not just a passive store:

Memory types

Four built-in types, matching the Claude Code convention:

• user — facts about the person (role, preferences, expertise level)
• feedback — rules the assistant should follow (do this, don't do that)
• project — current-state context that isn't in the code (deadlines, in-flight work)
• reference — pointers to external systems (Linear board URL, monitoring dashboard)

Tags + wiki-links

Beyond types, two cross-cutting organization features:

Tags — optional tags: [a, b, c] array in frontmatter. Queryable via list_memories({tags: [...]}) and the agent-memory list --tags "a,b" CLI. Filter is intersection — memories must have all listed tags. Tag names are lowercase a-z + digits + hyphen/underscore, max 40 chars.

---
name: deploy-process
description: Blue-green prod deployment
type: project
tags: [deployment, production, critical]
---

Wiki-links — write [[memory-name]] anywhere in a memory body and it becomes a link. find_backlinks returns memories that reference a given one; find_related ranks the full graph (outbound links, inbound backlinks, shared tags, content similarity) for discovery navigation.

---

CLI

The same binary is also a command-line tool. Useful in shell scripts, git hooks, cron, or just for quick lookups outside your editor.

agent-memory save user-likes-tabs --type user --description "Prefers tabs" --content "Always use tabs in new files."
agent-memory list
agent-memory list --type feedback
agent-memory search "tabs"                    # fuzzy, top 10 by relevance
agent-memory search "depoy" --limit 5         # typo-tolerant ("depoy" → "deploy")
agent-memory relevant "deployment" --max 3    # full memory bodies, LLM-ready
agent-memory get user-likes-tabs
agent-memory list --limit 20 --offset 40      # pagination
agent-memory delete user-likes-tabs           # soft delete — moves to .trash/
agent-memory restore user-likes-tabs          # restore the most recent trash entry
agent-memory doctor                            # check integrity
agent-memory doctor --rebuild-index            # repair MEMORY.md from disk
agent-memory stats                             # dashboard: counts, sizes, audit/trash
agent-memory log                               # last 20 entries from the audit log
agent-memory log --tail 50 --action delete     # filter by action, tail size
agent-memory verify deploy-process             # extract URLs/dates/file refs + staleness heuristics
agent-memory save my-mem --type project --description "X" --content "Body" --tags "production,critical"
agent-memory list --tags "production"          # filter by tag (intersection)
agent-memory backlinks deploy-process          # memories that link to deploy-process
agent-memory related deploy-process            # ranked discovery: links + tags + similarity
agent-memory sync init git@github.com:you/agent-memory.git    # multi-machine setup (one-time)
agent-memory sync push                         # commit + push local changes
agent-memory sync pull                         # fast-forward from remote
agent-memory sync status                       # local + ahead/behind state
agent-memory ui                                # launch the TUI (browse + edit interactively)

Multi-machine memory (git sync)

The killer feature for file-based memory: every dev machine has git, and markdown merges cleanly. agent-memory sync turns .agent-memory/ into a git repo pointed at a (private) remote, and your memories follow you across desktop/laptop/server.

# One-time setup
agent-memory sync init git@github.com:you/agent-memory.git

# End of the day on desktop
agent-memory sync push

# Pick up your laptop before bed
agent-memory sync pull

# Save a new memory while reading in bed
agent-memory save bedtime-thought --type project --description "..." --content "..."
agent-memory sync push

# Next morning at desktop
agent-memory sync pull          # picks up the bedtime memory

What's NOT synced (per-machine state, kept local):

• .lock — per-process file lock
• .events.jsonl — per-machine audit trail
• .trash/ — soft-delete staging

What IS synced: every memory file, the MEMORY.md index, and any .gitignore you add.

Commits use the identity agent-memory <agent-memory@local> by default — set GIT_AUTHOR_EMAIL / GIT_COMMITTER_EMAIL in your environment if you want per-machine attribution.

Audit log + structured logging

Every mutation appends one JSON line to .agent-memory/.events.jsonl:

{"ts":"2026-05-22T04:02:38.536Z","action":"save","name":"first-mem","type":"user","update":false,"bytes":6}
{"ts":"2026-05-22T04:02:39.414Z","action":"delete","name":"second-mem","trash":"1779422559413-second-mem.md"}
{"ts":"2026-05-22T04:02:39.712Z","action":"restore","name":"second-mem","binnedAt":"2026-05-22T04:02:39.413Z"}

Read it any way you want: cat, jq, the log / log_events tool, or a sidecar that ships it to your observability stack.

Operational logging is separate. Set AGENT_MEMORY_LOG=debug|info|warn|error (default info) and structured lines stream to stderr — won't pollute the MCP stdio channel.

Color output is on by default in TTYs. Set NO_COLOR=1 to disable, FORCE_COLOR=1 to force-enable in pipes.

Multi-line content can come from a file or stdin:

agent-memory save my-handoff --type project --description "Q3 handoff notes" --content-file handoff.md
cat conversation.txt | agent-memory save extracted-prefs --type user --description "Pulled from chat" --stdin

Importing from Claude Code

If you've been using Claude Code's built-in memory, bring it over:

# See what would be imported (dry run, no writes)
agent-memory import-claude-code --dry-run

# Filter to one project by substring match (case-insensitive)
agent-memory import-claude-code --project prefixcheck --dry-run

# Do the import
agent-memory import-claude-code --project prefixcheck

# Replace existing memories with the same names
agent-memory import-claude-code --project prefixcheck --overwrite

The importer walks ~/.claude/projects/*/memory/, parses each memory's YAML frontmatter (tolerantly — malformed files don't kill the run), flattens Claude Code's metadata.type field to top-level type, and writes to your current store. Existing memories with the same name are skipped unless you pass --overwrite.

---

Why files, not a database

You give up native semantic similarity search and structured entity-relation queries. You get a memory store that survives every tool change, every machine swap, every "wait, what was that AI telling me about this codebase six months ago?" — and that you can still read after a power outage.

The trade is real. For workflows that need vector recall or graph queries, a database-backed memory is the right tool. For workflows where memory is something you want to grep, edit, version-control, and audit by hand, this is.

---

Operator-grade by design

This server is built to be used daily, not to demo well once.

Shipped in v0.3:

• Atomic writes — tmp-file + rename pattern. Power-loss never leaves a half-written file.
• File locking — proper-lockfile around every mutation. Concurrent MCP server + CLI access can't corrupt the index.
• Soft delete — delete_memory moves to .trash/<timestamp>-<name>.md. restore_memory brings it back.
• Index recovery — agent-memory doctor reports orphan files, dangling entries, and parse errors. --rebuild-index rewrites MEMORY.md from disk.
• Schema versioning — every memory file gets a schema: 1 field so future format changes can migrate cleanly.
• Spec-compliant Resources — agent-memory://index + agent-memory://memory/{name}; clients can pin them as always-visible context.

Shipped in v0.4:

• Append-only event log at .events.jsonl — every mutation timestamped + JSON-structured for audit.
• agent-memory stats — dashboard of counts per type, total/avg/largest size, audit + trash counts.
• agent-memory log — paginated browser of the event log, filterable by action.
• Structured stderr logging — AGENT_MEMORY_LOG=debug|info|warn|error; safe to use alongside MCP stdio.
• Color output — auto-detected via TTY, respects NO_COLOR / FORCE_COLOR.

Shipped in v0.5:

• Fuse.js fuzzy search with field weights (name×3, description×2, body×1). Typo, partial, and word-order tolerant.
• Snippet highlighting — body-context excerpts shown under each match with ... markers.
• Relevance scoring — Fuse score inverted + scaled to 0-100 for human readability.
• relevant_memories(query, max=5) — sister tool to search that returns FULL memory bodies as a single markdown doc, built for LLM auto-context loading.
• Pagination — offset + limit on list_memories and limit on search_memories.

Shipped in v0.6:

• Vitest test suite — 25+ blackbox tests covering CLI + MCP server paths.
• GitHub Actions CI — runs tests on every push/PR across Node 20/22/24.
• COMPATIBILITY.md — known-working client matrix + quirks.

Shipped in v0.7 · the active context layer:

• MCP Prompts capability — 4 built-in workflows (extract_memories, summarize_topic, prepare_handoff, audit_stale) that the client surfaces as slash-commands.
• verify_memory tool — static analysis of a memory's URLs/dates/file refs with type-specific staleness heuristics. Plus the matching agent-memory verify <name> CLI.
• Conflict detection on save — fuzzy-matches new memories against existing ones; warns on near-duplicates without blocking the save (so the LLM can decide whether to merge, rename, or proceed).

Shipped in v0.8 · organization at scale:

• Tags — optional tags: [...] array in frontmatter. Queryable via list_memories and agent-memory list --tags "a,b". Intersection filter.
• [[wiki-links]] — write [[memory-name]] in any memory body, auto-detected.
• find_backlinks tool + agent-memory backlinks <name> CLI — "what links to this".
• find_related tool + agent-memory related <name> CLI — combines outbound + inbound links, shared tags, type match, and content similarity into a ranked discovery view.

Shipped in v0.9 · the moat — multi-machine memory via git:

• agent-memory sync init <remote-url> — convert .agent-memory/ into a git repo, push to remote.
• agent-memory sync push — auto-commit local changes + push.
• agent-memory sync pull — fast-forward from remote.
• agent-memory sync status — local state + commits ahead/behind origin.
• agent-memory sync log — history of cross-machine memory changes.
• sync_status / sync_push / sync_pull MCP tools — the LLM can do this too.
• Per-machine state (.lock, .events.jsonl, .trash/) auto-excluded from sync.
• Default commit identity injected (agent-memory@local) so machines without git config --global user.email work without setup.

Shipped in v0.10 · the visual identity (TUI):

• agent-memory ui — Ink-based terminal UI for browsing, filtering, searching, and editing memories without leaving the terminal.
• Type-filter quick-keys (0-4 cycle through all/user/feedback/project/reference)
• Fuzzy live search with /
• e opens the highlighted memory in $EDITOR (vim/notepad/nano/whatever) — saves back to disk
• d soft-deletes with y/n confirmation
• Detail pane previews the body of the selected memory
• Color-coded by type, tag chips inline

Landing in v0.11+:

• Folder support (.agent-memory/work/, .agent-memory/personal/)
• Memory packs for shareable curated bundles
• Web UI for browser-based memory browsing (companion to the TUI)
• Auto-context loading (LLM gets relevant memories transparently before each prompt)

---

Roadmap

Released

Coming next

• Folder support inside the store (.agent-memory/work/, .agent-memory/personal/) for multi-context separation
• Auto-context loading — server hook that auto-fires relevant_memories before each LLM turn so context flows transparently
• Memory packs — export/import shareable .tar.gz bundles of curated memories
• Browser companion UI (agent-memory web) for non-terminal users
• TUI polish — file-watching for auto-refresh, inline editing, sync push/pull as keybindings

Beyond

Optional local-embeddings sidecar (transformers.js, no API), team mode with diff/merge, browser extension to capture from chatgpt.com / claude.ai → memory, mobile companion.

Open an issue if you want one of these before I get to it.

---

License

MIT. Use it for whatever.

---

Author

@xultrax-web · built for the cross-client memory problem I kept running into. Part of PrefixCheck Labs.

Inspired by the file-based memory system in Anthropic's Claude Code.