Server data from the Official MCP Registry
Markdown memory for AI agents. Files you can read, edit, grep, and commit. Not a database.
Markdown memory for AI agents. Files you can read, edit, grep, and commit. Not a database.
Valid MCP server (2 strong, 2 medium validity signals). 2 known CVEs in dependencies (0 critical, 2 high severity) Package registry verified. Imported from the Official MCP Registry.
4 files analyzed · 3 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
This plugin requests these system permissions. Most are normal for its category.
Set these up before or after installing:
Environment variable: AGENT_MEMORY_DIR
Environment variable: AGENT_MEMORY_SCOPE
Environment variable: AGENT_MEMORY_LOG
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-xultrax-web-agent-memory-mcp": {
"env": {
"AGENT_MEMORY_DIR": "your-agent-memory-dir-here",
"AGENT_MEMORY_LOG": "your-agent-memory-log-here",
"AGENT_MEMORY_SCOPE": "your-agent-memory-scope-here"
},
"args": [
"-y",
"@xultrax-web/agent-memory-mcp"
],
"command": "npx"
}
}
}From the project's GitHub README.
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.
.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.
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:
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.
npx -y @xultrax-web/agent-memory-mcp
io.github.xultrax-web/agent-memory-mcp · browse at https://registry.modelcontextprotocol.io
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.
Same JSON, slightly different paths per client.
~/.cursor/mcp.json (or .cursor/mcp.json in your project):
{
"mcpServers": {
"agent-memory": {
"command": "npx",
"args": ["-y", "@xultrax-web/agent-memory-mcp"]
}
}
}
Cline → MCP Servers → Add:
{
"agent-memory": {
"command": "npx",
"args": ["-y", "@xultrax-web/agent-memory-mcp"]
}
}
%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
npxdoesn't resolve cleanly, wrap withcmd /c:{ "command": "cmd", "args": ["/c", "npx", "-y", "@xultrax-web/agent-memory-mcp"] }
~/.continue/config.json:
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@xultrax-web/agent-memory-mcp"]
}
}
]
}
}
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" }
| Tool | Purpose |
|---|---|
save_memory | Create or update a memory. Atomic write + locked. Validates name + type. Updates the index. |
search_memories | Fuzzy search (Fuse.js · typo-tolerant, word-order tolerant, partial matches). Returns top N with relevance 0-100 + body snippet. |
relevant_memories | Same matching as search, but returns full memory bodies as one markdown doc. Built for LLM auto-context. |
get_memory | Fetch one memory by name. Returns frontmatter + body. |
list_memories | List memories. Optional type filter. Paginated (default 50/page). |
delete_memory | Soft delete: moves the memory to .trash/<ts>-<name>.md. Recoverable until you empty .trash/ by hand. |
restore_memory | Restore a soft-deleted memory from .trash/. Picks the most recent trash entry for the name. |
doctor | Storage integrity check. Reports orphans, dangling index entries, unreadable files. Pass rebuild-index=true to repair MEMORY.md from disk. |
stats | Dashboard: counts per type, total size, largest memory, audit-log size, trash count. |
log_events | Read recent entries from the audit event log. Optional tail (default 20) + action filter. |
verify_memory | Re-evaluate a memory's claims. Extracts URLs/dates/file refs, flags stale-date signals, returns type-specific verification heuristics. Pairs with the audit_stale prompt. |
find_backlinks | List memories that link to the given memory via [[wiki-link]] syntax in their bodies. Useful for "what references this" views. |
find_related | Surface memories related to one by combining outbound links, inbound backlinks, shared tags, type match, and content similarity. Navigates the memory graph by association. |
sync_status | Report git-sync state: remote URL, branch, uncommitted local files, ahead/behind origin. |
sync_push | Commit local memory changes + push to the configured git remote. Auto-timestamps the commit message if none given. |
sync_pull | Fast-forward pull from the git remote. Refuses to pull if local changes are uncommitted. |
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:
| Prompt | Arguments | What it does |
|---|---|---|
extract_memories | none | LLM scans the current conversation, proposes candidate memories, and calls save_memory for each one (with type + description chosen). |
summarize_topic | topic | LLM pulls memories relevant to the topic via relevant_memories and synthesizes them into a single summary with citations. |
prepare_handoff | project (optional) | LLM walks project-type memories matching the filter and assembles a structured handoff doc (current state, open items, watch-outs). |
audit_stale | none | LLM evaluates project + reference memories for staleness and produces a triage list (likely stale / worth verifying / still fresh). |
Four built-in types, matching the Claude Code convention:
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.
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)
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 stagingWhat 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.
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
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.
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.
This server is built to be used daily, not to demo well once.
Shipped in v0.3:
proper-lockfile around every mutation. Concurrent MCP server + CLI access can't corrupt the index.delete_memory moves to .trash/<timestamp>-<name>.md. restore_memory brings it back.agent-memory doctor reports orphan files, dangling entries, and parse errors. --rebuild-index rewrites MEMORY.md from disk.schema: 1 field so future format changes can migrate cleanly.agent-memory://index + agent-memory://memory/{name}; clients can pin them as always-visible context.Shipped in v0.4:
.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.AGENT_MEMORY_LOG=debug|info|warn|error; safe to use alongside MCP stdio.NO_COLOR / FORCE_COLOR.Shipped in v0.5:
... markers.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.offset + limit on list_memories and limit on search_memories.Shipped in v0.6:
Shipped in v0.7 · the active context layer:
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.Shipped in v0.8 · organization at scale:
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..lock, .events.jsonl, .trash/) auto-excluded from sync.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./e opens the highlighted memory in $EDITOR (vim/notepad/nano/whatever) — saves back to diskd soft-deletes with y/n confirmationLanding in v0.11+:
.agent-memory/work/, .agent-memory/personal/)| Version | Highlights |
|---|---|
| v0.1 | Five-tool MVP, file storage, four-client config snippets |
| v0.2 | MCP Resources, Claude Code import (agent-memory import-claude-code), CLI mode, prettier baseline |
| v0.3 | Atomic writes, file locking, soft delete + restore_memory, doctor repair, schema versioning |
| v0.4 | Append-only event log (.events.jsonl), stats dashboard, log_events browser, color output |
| v0.5 | Fuzzy search via Fuse.js, relevance scoring, body-context snippets, relevant_memories, pagination |
| v0.6 | 25+ Vitest tests, GitHub Actions CI (Node 20/22/24 matrix), COMPATIBILITY.md |
| v0.7 | MCP Prompts (4 starter workflows), verify_memory, conflict detection on save |
| v0.8 | Tags, [[wiki-links]], find_backlinks, find_related |
| v0.8.1 | Trusted Publishing live · tokenless OIDC publishes to npm + MCP Registry on git tag |
| v0.9 | agent-memory sync · multi-machine memory via git remote (init/push/pull/status/log) |
| v0.10 | Ink-based TUI · agent-memory ui for visual browsing, search, and editing |
.agent-memory/work/, .agent-memory/personal/) for multi-context separationrelevant_memories before each LLM turn so context flows transparently.tar.gz bundles of curated memoriesagent-memory web) for non-terminal usersOptional 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.
MIT. Use it for whatever.
@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.
Be the first to review this server!
by Modelcontextprotocol · Developer Tools
Web content fetching and conversion for efficient LLM usage
by Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.