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 <MEMORY_DIR>/.keyring/hmac-key (CRP 1.0) or <MEMORY_DIR>/.keyring/ed25519-priv (CRP 1.1), 0600 perms on POSIX. Receipts are bound to their specific target (the action_hash caveat for delete memory <name>) 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 <MEMORY_DIR>/.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