Agent Memory Mcp

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

# 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

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

# 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:

{
  "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). 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).

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

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

.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"]
  }
}

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:

{
  "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):

{
  "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:

{
  "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

| 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
• Source: 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.