# Agent Memory Mcp > Markdown memory for AI agents. Files you can read, edit, grep, and commit. Not a database. Listed in the MCP Registry. - **Type:** MCP server - **Install:** `agentstack add mcp-xultrax-web-agent-memory-mcp` - **Verified:** Pending review - **Seller:** [xultrax-web](https://agentstack.voostack.com/s/xultrax-web) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [xultrax-web](https://github.com/xultrax-web) - **Source:** https://github.com/xultrax-web/agent-memory-mcp - **Website:** https://www.npmjs.com/package/@xultrax-web/agent-memory-mcp ## Install ```sh agentstack add mcp-xultrax-web-agent-memory-mcp ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # agent-memory-mcp > Guardrails for AI coding agents — write the rule once, every tool obeys, destructive actions get blocked. [](https://github.com/xultrax-web/agent-memory-mcp/actions/workflows/ci.yml) [](LICENSE) [](https://nodejs.org) [](https://modelcontextprotocol.io) [](cursor://anysphere.cursor-deeplink/mcp/install?name=agent-memory&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB4dWx0cmF4LXdlYi9hZ2VudC1tZW1vcnktbWNwIl19) [](https://smithery.ai/server/@xultrax-web/agent-memory-mcp) Your AI coding agent will eventually try to `rm -rf` the wrong folder, force-push to `main`, or delete the file you actually needed. **agent-memory-mcp** is the memory layer where you write the rule **once**, in plain markdown — and it _enforces itself_: - **Blocks destructive actions at the protocol layer.** The agent proposes an action; the server checks it against your rules and either refuses it or issues a short-lived, signed [Compliance Receipt](docs/compliance-receipt-protocol-1.0.md) it must present to act. Soft rules in a config file get ignored — this doesn't. - **One rule, every tool.** Save it once and it emits to `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, and `.gemini/` automatically — Claude Code, Cursor, Cline, Copilot, Gemini and Windsurf read the same rules, no plugin. - **Plain files you own.** `cat` it, `grep` it, edit it in vim, commit it to git, sync it across machines with `agent-memory sync`. No database, no daemon, no cloud — and if the AI gets it wrong, you fix it in a text editor. Memory — the rules, recipes, decisions, and context that survive every session and every tool — is the substrate. **Enforcement is the point.** Reference implementation of the [Compliance Receipt Protocol 1.0](docs/compliance-receipt-protocol-1.0.md), so other MCP servers can adopt the same receipts and interoperate. ## Quickstart · guarded in 60 seconds ```bash # After adding the server to your MCP client (see Install below), from your project: agent-memory init # drop in a starter guardrail pack (protect main, no rm -rf, no prod-data destruction, …) agent-memory install-hooks # make hard rules actually BLOCK in Claude Code (soft rules → ask) ``` Your agent is now guarded across every tool. Write your own rules with `save_rule` — they enforce _and_ emit to `AGENTS.md` / `CLAUDE.md` / `.cursor/rules` / `.gemini`. (CLI commands assume a global install — `npm i -g @xultrax-web/agent-memory-mcp` — or prefix with `npx -y`.) --- ## Memory as constraint · the v0.11 → v0.13 arc What v0.10 and below shipped: a great file-based memory store. What v0.11+ added: rules that _enforce themselves_. A `rule` memory type carries `severity` (hard / soft), `scope`, `applies_when`, `matches` regex patterns, `enforce_on` categories, and `last_verified` date. From those, the server projects companion files out to every AI tool and gates destructive operations via cryptographic receipts. ### 1. Rule memories project to every tool ```bash agent-memory save-rule no-emojis-ever \ --description "Never use emojis in commits, comments, or chat output." \ --severity hard \ --scope global \ --enforce-on commits,chat_responses \ --content "No emojis. Anywhere. Ever." agent-memory emit-companions # writes AGENTS.md + CLAUDE.md + .cursor/rules/*.mdc + .gemini/instructions.md ``` | Target | Path | Auto-loaded by | | -------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | | `agents` | `AGENTS.md` | Claude Code, Codex CLI, Cursor, Aider, Devin, Copilot, Gemini CLI, Windsurf, Amazon Q | | `claude` | `CLAUDE.md` | Claude Code (5-level hierarchy · managed/global/project/local/subdir) | | `cursor` | `.cursor/rules/operator-hard.mdc` (`alwaysApply: true`) + `operator-conventions.mdc` (agent-requested) | Cursor (MDC format) | | `gemini` | `.gemini/instructions.md` | Gemini CLI | Set `AGENT_MEMORY_AUTO_EMIT_DIR=/path/to/project` and the server re-emits all four files automatically on every rule save. ### 2. `check_action` · the protocol enforcement point ```bash # Agent proposes an action · server matches against rule store agent-memory check-action "delete the memory called old-project-notes" --type deletions # → On approval: returns a Compliance Receipt the agent passes back to destructive tools # → On deny: returns structured hard_violations + soft_warnings ``` MCP shape: ```jsonc { "name": "check_action", "arguments": { "action": "delete the memory called old-project-notes", "action_type": "deletions", "session_id": "sess_abc", }, } ``` **Tier 1** (deterministic, every client): action matched against `rule.matches` regex, filtered by `rule.enforce_on`. Hard violations block. Soft violations warn. Approved actions get a fresh receipt with 60s TTL. **Tier 2** (Sampling-enriched, shipped v0.11.7): for rules with `applies_when` natural-language conditions, the server uses MCP Sampling to ask the client's LLM whether the proposed action triggers the rule. Falls back to Tier 1 only if the client doesn't advertise Sampling capability. Works on Claude Desktop and VS Code Copilot; on Claude Code, Cursor, Cline, and Codex CLI you get Tier 1 only — which is enough to enforce the rules you've written. But `check_action` only gates _this server's own_ tools. To enforce your rules on the agent's **real** actions — the shell commands and file writes it runs — **`agent-memory install-hooks`** wires a `PreToolUse` hook into Claude Code: a **hard** rule **denies** the matching tool call, a **soft** rule **asks** you. Now an `rm -rf` or a force-push to `main` is actually _blocked_, not just advised. Run `agent-memory init` first for a starter ruleset. ### 3. Compliance Receipts · the cryptographic primitive Receipts are short-lived, signed bearer tokens with caveats (Macaroon pattern · [Birgisson et al., NDSS 2014](https://research.google/pubs/pub41892/)). The novel protocol primitive: server-issued tokens that bind to action + session + rules-version-hash + expiry. Tampering breaks the signature. Rule changes invalidate every outstanding receipt (because `rules_version` is part of the signed payload). ```typescript import { issueReceipt, validateReceipt } from "@xultrax-web/agent-memory-mcp"; const r = issueReceipt({ caveats: [ { type: "action", value: "delete_memory" }, { type: "session", value: "sess_abc123" }, ], ttl_seconds: 60, }); const v = validateReceipt(r, { required_caveats: [{ type: "action", value: "delete_memory" }], }); if (!v.valid) throw new Error(v.reason); ``` **Receipt-required `delete_memory` (v0.12.0 breaking change):** calling `delete_memory` without a valid receipt is refused. The two-step pattern is `check_action` → `delete_memory(name, receipt)`. The signing-key file lives at `/.keyring/hmac-key` (CRP 1.0) or `/.keyring/ed25519-priv` (CRP 1.1), `0600` perms on POSIX. Receipts are bound to their specific target (the `action_hash` caveat for `delete memory `) and are single-use; the `.keyring/` is **never committed or synced**, and `rotate_key` regenerates it after a suspected leak. **CRP 1.1 · Ed25519 federation (v0.13.0):** flip `CRP_SIGNING_MODE=ed25519` and the server signs with an asymmetric keypair instead of HMAC. The public key gets published at `/.keyring/ed25519-pub`, so other MCP servers can validate your receipts without sharing a secret. The protocol allows cross-server enforcement: server A issues a receipt for "delete X", server B validates and honors it. ### 4. `audit` · operational health for the rule store ```bash agent-memory audit # pretty colored terminal output agent-memory audit --json # structured JSON for tooling ``` Surfaces: - Rule count by severity (hard / soft / unspecified) - **Stale rules** · `last_verified` > 90 days, or never verified - **Pattern conflicts** · two rules sharing an `enforce_on` AND an identical regex in `matches` - **Recent denials** · `check_action` calls that blocked an action (spot over-aggressive rules) - **Unreceipted destructive ops** · should be empty in v0.12+; non-empty means a client is calling `delete_memory` without going through `check_action` The `healthy` flag is true iff no stale rules, no conflicts, no unreceipted ops. ### 5. CRP 1.0 / 1.1 as a portable spec The receipt protocol is documented standalone at [docs/compliance-receipt-protocol-1.0.md](docs/compliance-receipt-protocol-1.0.md). Other MCP servers can adopt the same format + validation rules to interoperate · `agent-memory-mcp` is the reference implementation. The spec covers: receipt structure, canonical encoding, signing (HMAC-SHA256 for 1.0, Ed25519 for 1.1), validation order, rules-version hashing, reserved caveat types, MCP integration patterns, security considerations, cross-server adoption, and test vectors. --- ## What you get ```text .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: ```markdown --- 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) ```bash 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 ```bash 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): ```json { "mcpServers": { "agent-memory": { "command": "npx", "args": ["-y", "@xultrax-web/agent-memory-mcp"] } } } ``` ### Cline (VS Code extension) Cline → MCP Servers → Add: ```json { "agent-memory": { "command": "npx", "args": ["-y", "@xultrax-web/agent-memory-mcp"] } } ``` ### VS Code (Copilot Chat) > **Two VS Code paths.** The Cline section above is for the Cline extension specifically (its own MCP server UI). This section is for VS Code's native MCP support — GitHub Copilot Chat reads it directly. Pick whichever matches your assistant; both coexist fine. `.vscode/mcp.json` (workspace) or via User Settings → Edit `mcp.json`: ```json { "servers": { "agent-memory": { "type": "stdio", "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): ```json { "mcpServers": { "agent-memory": { "command": "npx", "args": ["-y", "@xultrax-web/agent-memory-mcp"] } } } ``` > **Windows note:** if `npx` doesn't resolve cleanly, wrap with `cmd /c`: > > ```json > { "command": "cmd", "args": ["/c", "npx", "-y", "@xultrax-web/agent-memory-mcp"] } > ``` ### Continue.dev `~/.continue/config.json`: ```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: ```json "env": { "AGENT_MEMORY_SCOPE": "global" } ``` Global memories live at `~/.agent-memory/`. Custom path: ```json "env": { "AGENT_MEMORY_DIR": "/abs/path/to/memory" } ``` --- ## Tools | 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). … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [xultrax-web](https://github.com/xultrax-web) - **Source:** [xultrax-web/agent-memory-mcp](https://github.com/xultrax-web/agent-memory-mcp) - **License:** MIT - **Homepage:** https://www.npmjs.com/package/@xultrax-web/agent-memory-mcp Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-xultrax-web-agent-memory-mcp - Seller: https://agentstack.voostack.com/s/xultrax-web - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.