Agent Memory MCP

agent-memory-mcp

Guardrails for AI coding agents — write the rule once, every tool obeys, destructive actions get blocked.

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 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, 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

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

`