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)

`