Integrates with Amazon Q by emitting companion rule files that Amazon Q automatically reads, enabling consistent rule enforcement across AI coding assistants.
Integrates with GitHub Copilot by emitting AGENTS.md and other companion files that Copilot automatically reads to enforce rules.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@agent-memory-mcp save a hard rule to block force-push to main"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
# 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.)
Related MCP server: Agent Policy Gateway MCP Server
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.
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.mdTarget | Path | Auto-loaded by |
|
| Claude Code, Codex CLI, Cursor, Aider, Devin, Copilot, Gemini CLI, Windsurf, Amazon Q |
|
| Claude Code (5-level hierarchy · managed/global/project/local/subdir) |
|
| Cursor (MDC format) |
|
| Gemini CLI |
Set AGENT_MEMORY_AUTO_EMIT_DIR=/path/to/project and the server re-emits all four files automatically on every rule save.
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_warningsMCP 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.
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.
audit · operational health for the rule storeagent-memory audit # pretty colored terminal output
agent-memory audit --json # structured JSON for toolingSurfaces:
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.
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.
.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.mdA 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.
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.
npx -y @xultrax-web/agent-memory-mcpio.github.xultrax-web/agent-memory-mcp · browse at https://registry.modelcontextprotocol.io
git clone https://github.com/xultrax-web/agent-memory-mcp
cd agent-memory-mcp
npm install
npm run build
node dist/index.jsThe server speaks MCP over stdio. You don't run it directly — your MCP client launches it.
Same JSON, slightly different paths per client.
~/.cursor/mcp.json (or .cursor/mcp.json in your project):
{
"mcpServers": {
"agent-memory": {
"command": "npx",
"args": ["-y", "@xultrax-web/agent-memory-mcp"]
}
}
}Cline → MCP Servers → Add:
{
"agent-memory": {
"command": "npx",
"args": ["-y", "@xultrax-web/agent-memory-mcp"]
}
}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"]
}
}
}%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
npxdoesn't resolve cleanly, wrap withcmd /c:{ "command": "cmd", "args": ["/c", "npx", "-y", "@xultrax-web/agent-memory-mcp"] }
~/.continue/config.json:
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@xultrax-web/agent-memory-mcp"]
}
}
]
}
}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" }Tool | Purpose |
| Create or update a memory. Atomic write + locked. Validates name + type. Updates the index. |
| Fuzzy search (Fuse.js · typo-tolerant, word-order tolerant, partial matches). Returns top N with relevance 0-100 + body snippet. |
| Same matching as search, but returns full memory bodies as one markdown doc. Built for LLM auto-context. |
| Fetch one memory by name. Returns frontmatter + body. |
| List memories. Optional |
| Receipt-required, target-bound, single-use. Pass a Compliance Receipt from |
| Restore a soft-deleted memory from |
| Storage integrity check. Reports orphans, dangling index entries, unreadable files. Pass |
| Dashboard: counts per type, total size, largest memory, audit-log size, trash count. |
| Read recent entries from the audit event log. Optional |
| Re-evaluate a memory's claims. Extracts URLs/dates/file refs, flags stale-date signals, returns type-specific verification heuristics. Pairs with the |
| List memories that link to the given memory via |
| Surface memories related to one by combining outbound links, inbound backlinks, shared tags, type match, and content similarity. Navigates the memory graph by association. |
| Report git-sync state: remote URL, branch, uncommitted local files, ahead/behind origin. |
| Commit local memory changes + push to the configured git remote. Auto-timestamps the commit message if none given. |
| Fast-forward pull from the git remote. Refuses to pull if local changes are uncommitted. |
| v0.11+. Create or update a |
| v0.11+. List just rule memories, optionally filtered by severity or enforce_on category. |
| v0.11.1+. Project the rule store out to |
| v0.11.3+. Tier-1 deterministic + Tier-2 Sampling rule check. Returns |
| v0.11.4+. Operational health for the rule store: stale rules, pattern conflicts, recent denials, unreceipted destructive ops. Returns JSON or pretty-prints. |
| v0.14+. Rotate the receipt-signing HMAC / Ed25519 keys, invalidating every outstanding receipt. Remediation after a key leak. Optional |
| v0.15+. Install a starter guardrail pack (protect main, no rm -rf, no prod-data destruction, no curl|sh, flag secrets) and emit it to every tool. |
| v0.15+. Validate ANOTHER server's CRP 1.1 (Ed25519) receipt with its public key · the federation primitive. Pass |
The server exposes 4 built-in MCP prompts that clients (Claude Desktop, Cursor, etc.) surface as slash-commands. These turn memory into an active workflow layer, not just a passive store:
Prompt | Arguments | What it does |
| none | LLM scans the current conversation, proposes candidate memories, and calls |
|
| LLM pulls memories relevant to the topic via |
|
| LLM walks project-type memories matching the filter and assembles a structured handoff doc (current state, open items, watch-outs). |
| none | LLM evaluates project + reference memories for staleness and produces a triage list (likely stale / worth verifying / still fresh). |
Five built-in types. The first four match the Claude Code convention; rule is what v0.11 added:
user — facts about the person (role, preferences, expertise level)
feedback — soft guidance for the assistant (prefer this style, lean toward that approach)
project — current-state context that isn't in the code (deadlines, in-flight work)
reference — pointers to external systems (Linear board URL, monitoring dashboard)
rule — constraints to enforce, not just facts to recall. Carries severity, scope, matches, enforce_on, applies_when, last_verified. Projects to companion files; gates check_action.
Beyond types, two cross-cutting organization features:
Tags — optional tags: [a, b, c] array in frontmatter. Queryable via list_memories({tags: [...]}) and the agent-memory list --tags "a,b" CLI. Filter is intersection — memories must have all listed tags. Tag names are lowercase a-z + digits + hyphen/underscore, max 40 chars.
---
name: deploy-process
description: Blue-green prod deployment
type: project
tags: [deployment, production, critical]
---Wiki-links — write [[memory-name]] anywhere in a memory body and it becomes a link. find_backlinks returns memories that reference a given one; find_related ranks the full graph (outbound links, inbound backlinks, shared tags, content similarity) for discovery navigation.
The same binary is also a command-line tool. Useful in shell scripts, git hooks, cron, or just for quick lookups outside your editor.
agent-memory save user-likes-tabs --type user --description "Prefers tabs" --content "Always use tabs in new files."
agent-memory list
agent-memory list --type feedback
agent-memory search "tabs" # fuzzy, top 10 by relevance
agent-memory search "depoy" --limit 5 # typo-tolerant ("depoy" → "deploy")
agent-memory relevant "deployment" --max 3 # full memory bodies, LLM-ready
agent-memory get user-likes-tabs
agent-memory list --limit 20 --offset 40 # pagination
agent-memory delete user-likes-tabs # soft delete — moves to .trash/
agent-memory restore user-likes-tabs # restore the most recent trash entry
agent-memory doctor # check integrity
agent-memory doctor --rebuild-index # repair MEMORY.md from disk
agent-memory stats # dashboard: counts, sizes, audit/trash
agent-memory log # last 20 entries from the audit log
agent-memory log --tail 50 --action delete # filter by action, tail size
agent-memory verify deploy-process # extract URLs/dates/file refs + staleness heuristics
agent-memory save my-mem --type project --description "X" --content "Body" --tags "production,critical"
agent-memory list --tags "production" # filter by tag (intersection)
agent-memory backlinks deploy-process # memories that link to deploy-process
agent-memory related deploy-process # ranked discovery: links + tags + similarity
agent-memory sync init git@github.com:you/agent-memory.git # multi-machine setup (one-time)
agent-memory sync push # commit + push local changes
agent-memory sync pull # fast-forward from remote
agent-memory sync status # local + ahead/behind state
agent-memory ui # launch the TUI (browse + edit interactively)
# v0.11+ · rules and enforcement
agent-memory save-rule no-emoji --severity hard --enforce-on commits,chat_responses \
--matches "emoji|:[a-z_]+:" --content "No emojis. Anywhere. Ever."
agent-memory list-rules # rule memories only
agent-memory list-rules --severity hard # filter by severity
agent-memory emit-companions # write AGENTS.md + CLAUDE.md + .cursor/rules + .gemini
agent-memory emit-companions --target agents,claude # filter targets
agent-memory check-action "delete old notes" --type deletions # returns approval + receipt JSON
agent-memory audit # pretty operational health report
agent-memory audit --json # structured JSON for toolingThe killer feature for file-based memory: every dev machine has git, and markdown merges cleanly. agent-memory sync turns .agent-memory/ into a git repo pointed at a (private) remote, and your memories follow you across desktop/laptop/server.
# One-time setup
agent-memory sync init git@github.com:you/agent-memory.git
# End of the day on desktop
agent-memory sync push
# Pick up your laptop before bed
agent-memory sync pull
# Save a new memory while reading in bed
agent-memory save bedtime-thought --type project --description "..." --content "..."
agent-memory sync push
# Next morning at desktop
agent-memory sync pull # picks up the bedtime memoryWhat's NOT synced (per-machine state, kept local):
.lock — per-process file lock
.events.jsonl — per-machine audit trail
.trash/ — soft-delete staging
What IS synced: every memory file, the MEMORY.md index, and any .gitignore you add.
Commits use the identity agent-memory <agent-memory@local> by default — set GIT_AUTHOR_EMAIL / GIT_COMMITTER_EMAIL in your environment if you want per-machine attribution.
Every mutation appends one JSON line to .agent-memory/.events.jsonl:
{"ts":"2026-05-22T04:02:38.536Z","action":"save","name":"first-mem","type":"user","update":false,"bytes":6}
{"ts":"2026-05-22T04:02:39.414Z","action":"delete","name":"second-mem","trash":"1779422559413-second-mem.md"}
{"ts":"2026-05-22T04:02:39.712Z","action":"restore","name":"second-mem","binnedAt":"2026-05-22T04:02:39.413Z"}Read it any way you want: cat, jq, the log / log_events tool, or a sidecar that ships it to your observability stack.
Operational logging is separate. Set AGENT_MEMORY_LOG=debug|info|warn|error (default info) and structured lines stream to stderr — won't pollute the MCP stdio channel.
Color output is on by default in TTYs. Set NO_COLOR=1 to disable, FORCE_COLOR=1 to force-enable in pipes.
Multi-line content can come from a file or stdin:
agent-memory save my-handoff --type project --description "Q3 handoff notes" --content-file handoff.md
cat conversation.txt | agent-memory save extracted-prefs --type user --description "Pulled from chat" --stdinIf you've been using Claude Code's built-in memory, bring it over:
# See what would be imported (dry run, no writes)
agent-memory import-claude-code --dry-run
# Filter to one project by substring match (case-insensitive)
agent-memory import-claude-code --project prefixcheck --dry-run
# Do the import
agent-memory import-claude-code --project prefixcheck
# Replace existing memories with the same names
agent-memory import-claude-code --project prefixcheck --overwriteThe importer walks ~/.claude/projects/*/memory/, parses each memory's YAML frontmatter (tolerantly — malformed files don't kill the run), flattens Claude Code's metadata.type field to top-level type, and writes to your current store. Existing memories with the same name are skipped unless you pass --overwrite.
You give up native semantic similarity search and structured entity-relation queries. You get a memory store that survives every tool change, every machine swap, every "wait, what was that AI telling me about this codebase six months ago?" — and that you can still read after a power outage.
The trade is real. For workflows that need vector recall or graph queries, a database-backed memory is the right tool. For workflows where memory is something you want to grep, edit, version-control, and audit by hand, this is.
This server is built to be used daily, not to demo well once.
Shipped in v0.3:
Atomic writes — tmp-file + rename pattern. Power-loss never leaves a half-written file.
File locking — proper-lockfile around every mutation. Concurrent MCP server + CLI access can't corrupt the index.
Soft delete — delete_memory moves to .trash/<timestamp>-<name>.md. restore_memory brings it back.
Index recovery — agent-memory doctor reports orphan files, dangling entries, and parse errors. --rebuild-index rewrites MEMORY.md from disk.
Schema versioning — every memory file gets a schema: 1 field so future format changes can migrate cleanly.
Spec-compliant Resources — agent-memory://index + agent-memory://memory/{name}; clients can pin them as always-visible context.
Shipped in v0.4:
Append-only event log at .events.jsonl — every mutation timestamped + JSON-structured for audit.
agent-memory stats — dashboard of counts per type, total/avg/largest size, audit + trash counts.
agent-memory log — paginated browser of the event log, filterable by action.
Structured stderr logging — AGENT_MEMORY_LOG=debug|info|warn|error; safe to use alongside MCP stdio.
Color output — auto-detected via TTY, respects NO_COLOR / FORCE_COLOR.
Shipped in v0.5:
Fuse.js fuzzy search with field weights (name×3, description×2, body×1). Typo, partial, and word-order tolerant.
Snippet highlighting — body-context excerpts shown under each match with ... markers.
Relevance scoring — Fuse score inverted + scaled to 0-100 for human readability.
relevant_memories(query, max=5) — sister tool to search that returns FULL memory bodies as a single markdown doc, built for LLM auto-context loading.
Pagination — offset + limit on list_memories and limit on search_memories.
Shipped in v0.6:
Vitest test suite — 25+ blackbox tests covering CLI + MCP server paths.
GitHub Actions CI — runs tests on every push/PR across Node 20/22/24.
COMPATIBILITY.md — known-working client matrix + quirks.
Shipped in v0.7 · the active context layer:
MCP Prompts capability — 4 built-in workflows (extract_memories, summarize_topic, prepare_handoff, audit_stale) that the client surfaces as slash-commands.
verify_memory tool — static analysis of a memory's URLs/dates/file refs with type-specific staleness heuristics. Plus the matching agent-memory verify <name> CLI.
Conflict detection on save — fuzzy-matches new memories against existing ones; warns on near-duplicates without blocking the save (so the LLM can decide whether to merge, rename, or proceed).
Shipped in v0.8 · organization at scale:
Tags — optional tags: [...] array in frontmatter. Queryable via list_memories and agent-memory list --tags "a,b". Intersection filter.
[[wiki-links]] — write [[memory-name]] in any memory body, auto-detected.
find_backlinks tool + agent-memory backlinks <name> CLI — "what links to this".
find_related tool + agent-memory related <name> CLI — combines outbound + inbound links, shared tags, type match, and content similarity into a ranked discovery view.
Shipped in v0.9 · the moat — multi-machine memory via git:
agent-memory sync init <remote-url> — convert .agent-memory/ into a git repo, push to remote.
agent-memory sync push — auto-commit local changes + push.
agent-memory sync pull — fast-forward from remote.
agent-memory sync status — local state + commits ahead/behind origin.
agent-memory sync log — history of cross-machine memory changes.
sync_status / sync_push / sync_pull MCP tools — the LLM can do this too.
Per-machine state (.lock, .events.jsonl, .trash/) auto-excluded from sync.
Default commit identity injected (agent-memory@local) so machines without git config --global user.email work without setup.
Shipped in v0.10 · the visual identity (TUI):
agent-memory ui — Ink-based terminal UI for browsing, filtering, searching, and editing memories without leaving the terminal.
Type-filter quick-keys (0-4 cycle through all/user/feedback/project/reference)
Fuzzy live search with /
e opens the highlighted memory in $EDITOR (vim/notepad/nano/whatever) — saves back to disk
d soft-deletes with y/n confirmation
Detail pane previews the body of the selected memory
Color-coded by type, tag chips inline
Shipped in v0.11 · memory as constraint:
rule memory type with severity / scope / matches / enforce_on / applies_when / last_verified
save_rule + list_rules tools and CLI commands
emit_companions projects rules to AGENTS.md + CLAUDE.md + .cursor/rules/*.mdc + .gemini/instructions.md
AGENT_MEMORY_AUTO_EMIT_DIR triggers re-emission on every rule save
Compliance Receipts (issueReceipt / validateReceipt) — HMAC-SHA256 bearer tokens with Macaroon-style caveats, bound to rules_version so rule changes invalidate outstanding tokens
check_action MCP tool (Tier 1 deterministic; Tier 2 Sampling-enriched on v0.11.7 for clients that advertise the capability)
audit command — stale rules, pattern conflicts, recent denials, unreceipted destructive ops
CRP 1.0 protocol spec — portable, vendor-neutral
Shipped in v0.12 · the wedge made teeth (breaking change):
delete_memory REQUIRES a valid receipt. Calling without one is refused at the tool boundary.
Two-step pattern is canonical: check_action → receipt → delete_memory(name, receipt)
Audit log no longer needs an "unreceipted ops" warning class to surface escapes — there are none
Shipped in v0.13 · cross-server federation:
CRP 1.1 · Ed25519 asymmetric signing (set CRP_SIGNING_MODE=ed25519)
Public key published at <MEMORY_DIR>/.keyring/ed25519-pub so other servers can validate without sharing a secret
9 dedicated Ed25519 tests verifying keypair generation, signing, and cross-server validation paths
Version | Highlights |
v0.1 | Five-tool MVP, file storage, four-client config snippets |
v0.2 | MCP Resources, Claude Code import ( |
v0.3 | Atomic writes, file locking, soft delete + |
v0.4 | Append-only event log ( |
v0.5 | Fuzzy search via Fuse.js, relevance scoring, body-context snippets, |
v0.6 | 25+ Vitest tests, GitHub Actions CI (Node 20/22/24 matrix), |
v0.7 | MCP Prompts (4 starter workflows), |
v0.8 | Tags, |
v0.8.1 | Trusted Publishing live · tokenless OIDC publishes to npm + MCP Registry on git tag |
v0.9 |
|
v0.10 | Ink-based TUI · |
v0.11.0 |
|
v0.11.1 |
|
v0.11.2 | Compliance Receipts primitive · HMAC-SHA256 tokens with Macaroon-style caveats |
v0.11.3 |
|
v0.11.4 |
|
v0.11.5 | CRP 1.0 protocol spec — portable, vendor-neutral enforcement primitive |
v0.11.6 | Repositioning · "codify how you work, every AI tool obeys" |
v0.11.7 | Tier-2 Sampling-enriched |
v0.12 | Receipt REQUIRED on |
v0.13 | CRP 1.1 · Ed25519 asymmetric signing for cross-server federation |
Receipt-gated restore_memory and doctor --rebuild-index (same check_action flow)
Federation example · a second reference MCP server that issues + validates CRP 1.1 receipts
Auto-context loading — server hook that auto-fires relevant_memories before each LLM turn
Folder support inside the store (.agent-memory/work/, .agent-memory/personal/)
Memory packs — export/import shareable .tar.gz bundles of curated memories
Browser companion UI (agent-memory web)
TUI polish — file-watching for auto-refresh, inline editing, sync as keybindings
Optional local-embeddings sidecar (transformers.js, no API), team mode with diff/merge, browser extension to capture from chatgpt.com / claude.ai → memory, mobile companion.
Open an issue if you want one of these before I get to it.
MIT. Use it for whatever.
@xultrax-web · built for the cross-client memory problem I kept running into. Part of PrefixCheck Labs.
Inspired by the file-based memory system in Anthropic's Claude Code.
v0.11.4 · operational health report for the rule store. Surfaces: rule count by severity, stale rules (last_verified > 90 days or null), pattern conflicts (two rules sharing an enforce_on category AND an identical regex pattern), recent check_action denials, and recent unreceipted destructive ops. Default returns pretty-printed text; pass {format: 'json'} for structured output. Run daily-ish · the report is fast and gives the operator a single view of what's drifting.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Output format. Default 'pretty' (human-readable colored text). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral transparency. It notes the tool outputs 'pretty-printed text' by default or JSON when requested, and implies it is non-destructive by calling it a 'report'. However, it does not explicitly confirm read-only or mention side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (four sentences) and well-structured: first sentence declares purpose, second enumerates contents, third gives format option, and fourth offers usage guidance. Every sentence adds value with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple schema (one optional parameter) and no output schema, the description adequately covers the return format options and lists the report's contents. However, it does not specify the structure of the JSON output, which could be useful for programmatic consumption.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds marginal value by restating the format parameter's default and output type ('Default returns pretty-printed text; pass {format: "json"} for structured output'), but does not provide additional meaning beyond the schema's own description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as an 'operational health report for the rule store' and lists specific data it surfaces (rule count by severity, stale rules, pattern conflicts, etc.), providing a precise verb+resource combination that distinguishes it from sibling tools like list_rules or save_rule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description suggests a usage cadence ('Run daily-ish') and mentions the report is fast, but it does not explicitly state when to use this tool versus alternatives such as stats or doctor, nor does it provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
v0.11.3 · the protocol enforcement point. Pass a proposed action description + its category; the server matches against rule memories (type=rule) and either:
APPROVES: returns a short-lived Compliance Receipt (HMAC-signed, 60s default) the agent can pass to destructive tools (e.g. delete_memory) as proof of compliance.
DENIES: returns structured hard_violations (severity:hard rules that block) and/or soft_warnings (severity:soft rules that warn but allow).
Tier 1 (deterministic) matches the action against rule.matches regexes + rule.enforce_on category filter. Works on every MCP client. Tier 2 (v0.11.7+) calls back to the client via MCP sampling/createMessage to judge rule.applies_when natural-language conditions. Auto-enabled on clients that declared the sampling capability; silently skipped on clients that didn't.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Description of the proposed action. Plain prose · 'delete the memory called X', 'push to main branch', 'commit with message Y', etc. | |
| session_id | No | Optional session identifier · binds the issued receipt to this session via a caveat. | |
| action_type | Yes | Action category for rule.enforce_on matching. Examples: 'deletions', 'commits', 'pushes', 'file_writes', 'chat_responses', 'tool_calls'. | |
| use_sampling | No | Opt out of Tier-2 Sampling enrichment (default true). Set false for batched/scripted use where the Sampling round-trip would add latency. CLI invocations default this to false automatically. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden. It details two enforcement tiers, conditions for approval/denial, session caveats, and sampling behavior. No contradictions and provides complete behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points and subheadings, but slightly verbose. Every sentence is meaningful and front-loaded with a clear summary line. Minor reduction in length possible without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains the two possible returns (Compliance Receipt or violations) and their structure. Covers all relevant aspects for tool usage including tiers and sampling. Complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant value: provides examples for 'action' (e.g., 'delete the memory called X'), explains 'action_type' categories, specifies 'session_id' binds via a caveat, and clarifies 'use_sampling' defaults. Greatly enhances understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it is a 'protocol enforcement point' that checks actions against rule memories. Provides specific verb 'check_action' and resource 'rule memories', and distinguishes from other tools like 'delete_memory' by explaining its role as a compliance gate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explanation includes when to use ('before destructive tools') and opt-out for sampling. However, it does not explicitly list when not to use or mention direct alternatives, though the context is clear from the tool's purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a memory to .trash/ (soft delete). The file is removed from the index but recoverable via restore_memory until you manually empty .trash/. Receipt REQUIRED and bound to THIS memory: first call check_action({action: 'delete memory ', action_type: 'deletions'}) — using that EXACT action string — to obtain a fresh Compliance Receipt, then pass it as receipt. The receipt must carry {action_type: 'deletions'} AND the matching action_hash for 'delete memory ', and is single-use — it cannot be replayed to delete a different memory or the same one twice.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The memory's name slug | |
| receipt | Yes | REQUIRED · Compliance Receipt (object or JSON string) from check_action with action_type=deletions. Without this, the delete is refused. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the soft delete mechanism, recoverability, and receipt requirement including single-use and non-replayability. Despite no annotations, it discloses key behaviors. Lacks details on edge cases like non-existent memory or receipt format validation beyond refusal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single dense paragraph of three sentences front-loaded with the main action. Every sentence is essential, no redundancy. Efficiently conveys all needed information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (receipt from another tool), the description is fully complete. Covers soft delete, recoverability, receipt requirement, and constraints. Mentions sibling tool restore_memory. No gaps for an agent to misuse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds substantial meaning: explains receipt is a Compliance Receipt from check_action with specific action_type and action string, single-use binding. This goes well beyond the schema's brief descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool performs a soft delete by moving a memory to .trash/. Distinguishes from restore_memory by mentioning recoverability. Verb 'delete' and resource 'memory' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (soft delete) and mentions restore_memory for recovery. Provides detailed prerequisite: must call check_action with exact action string and obtain a fresh Compliance Receipt. Clarifies receipt binding and single-use nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check storage integrity. Reports orphan files (on disk but not indexed), dangling index entries (no file), unreadable files, and invalid types. Pass rebuild-index=true to reconstruct MEMORY.md from disk.
| Name | Required | Description | Default |
|---|---|---|---|
| rebuild-index | No | If true, rewrite MEMORY.md to match what's on disk. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It mentions reporting and reconstruction, but does not detail potential side effects (e.g., whether rebuilding modifies existing data irreversibly) or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancy. Front-loaded with main purpose, then details reports and optional mode. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers inputs, behavior, and output reports. Lacks mention of prerequisites or output format, but these are minor given the tool's diagnostic nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter is already documented. Description adds context by explaining the effect of rebuild-index=true (rewrite MEMORY.md from disk), but this is minor reinforcement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool checks storage integrity and lists specific types of issues (orphan files, dangling entries, etc.). It distinguishes from siblings like verify_memory and audit by focusing on disk integrity vs. memory content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description specifies the primary use case (check storage integrity) and provides condition for using the rebuild-index parameter. It does not explicitly mention when not to use or alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Regenerate companion rule files from the current rule memories. Writes one or more of: AGENTS.md (universal cross-tool standard, Linux Foundation), CLAUDE.md (Claude Code's 5-level hierarchy), .cursor/rules/*.mdc (Cursor's MDC format · hard rules get alwaysApply:true, soft rules become description-driven), .gemini/instructions.md (Gemini CLI). Default writes ALL four targets. Use targets to filter. Output dir resolves from out_dir, then AGENT_MEMORY_COMPANION_DIR env, then process.cwd().
| Name | Required | Description | Default |
|---|---|---|---|
| out_dir | No | Optional output directory. Defaults to AGENT_MEMORY_COMPANION_DIR env, then process.cwd(). | |
| targets | No | Which companion files to emit. Omit (or pass empty) to emit all four. Examples: ['agents'] for AGENTS.md only, ['claude','cursor'] for Claude Code + Cursor. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description fully describes the write operation and output file formats. However, it does not explicitly state that files will be overwritten or mention error conditions, though 'regenerate' implies replacement. Slight gap in specifying side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient, using three sentences to convey purpose, target files, and parameter usage. The list in the second sentence is informative but slightly lengthy; still no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description covers input parameters and behavior sufficiently. It lacks explicit mention of return values (e.g., success message or list of written files), but the operation is simple enough that this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining directory resolution order and default behavior for the `targets` parameter, including examples. This goes beyond the schema's descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: regenerating companion rule files from current rule memories. It lists each specific file format (AGENTS.md, CLAUDE.md, etc.), making it distinct from sibling tools like save_rule or list_rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains default behavior (writes all four targets) and how to filter using the `targets` parameter. Provides examples of filtering, giving clear guidance on when to use the tool with or without parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List memories that link to the given memory via [[wiki-link]] syntax in their bodies. Useful for building a 'what references this' view.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The memory's name slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It implies a read-only operation by listing backlinks, but does not disclose potential side effects, authentication needs, or behavior when no backlinks exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence stating the core functionality, plus a brief usage note. Every word adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers the basic functionality well. However, it could be more complete by mentioning the output format or search behavior (e.g., case sensitivity).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'name' is present with a schema description. The tool description adds no further semantics beyond the schema, which already clearly explains 'The memory's name slug'. With 100% schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'memories that link to the given memory', and specifies the wiki-link syntax. It distinguishes itself from sibling tools like get_memory or search_memories by focusing on backlinks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case: 'building a what references this view'. However, it does not explicitly state when not to use it or mention alternative tools for similar tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single memory by name.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The memory's name slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It implies a read-only operation but does not confirm this, nor mention permissions, error handling (e.g., returns null if not found), or any side effects. More details would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple, the lack of a return description is a gap. Without an output schema, the description should hint at the return type (e.g., memory object or null). Adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description of the 'name' parameter as 'The memory's name slug'. The tool description adds no additional meaning beyond the schema, so baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch', the resource 'memory', and the method 'by name'. This distinguishes it from siblings like 'search_memories' or 'list_memories', which operate on sets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or not use this tool. The context implies use when the exact name is known, but no alternatives are mentioned. This is adequate for a simple fetch but lacks depth.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Install a starter guardrail pack — sensible hard/soft rules (protect main, block rm -rf, no prod data destruction, no curl|sh, flag secrets) — and emit them to every tool's companion files. Zero-config protection on day one. Pass force=true to overwrite same-named rules. Pair with agent-memory install-hooks so hard rules actually block tool calls.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Overwrite existing starter rules. Default false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It states that rules are installed and emitted to companion files, but does not disclose side effects (e.g., whether existing configurations are modified irreversibly) or the exact return value. The behavior is partially transparent but lacks detail on consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, highly concise, and front-loads the primary action. Every sentence adds value: stating the action, listing examples, giving default behavior, and providing pairing advice. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description adequately explains the tool's purpose and behavior for a simple setup tool. It lacks details about the return value (e.g., success status, list of installed rules) and potential side effects, making it incomplete for full transparency.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the `force` parameter with a description. The tool description adds context: 'Pass force=true to overwrite same-named rules,' which clarifies the effect beyond the schema's 'Overwrite existing starter rules.' This adds meaningful nuance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool installs a starter guardrail pack with specific examples (protect main, block rm -rf, etc.) and explains it emits rules to companion files. It distinguishes itself from sibling tools like `save_rule` (individual rules) and `audit` (checking) by focusing on initial setup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: 'Zero-config protection on day one' and advises pairing with `install-hooks`. It mentions the `force` parameter for overwriting. However, it does not explicitly state when not to use this tool or mention alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List stored memories, optionally filtered by type and/or tags. Paginated.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Optional tag filter — memories must have ALL listed tags (intersection). Can also be passed as a comma-separated string. | |
| type | No | Optional filter — only list memories of this type | |
| limit | No | Max results per page (default 50). | |
| offset | No | Skip this many results (default 0). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It indicates a read operation with optional filters and pagination, but does not elaborate on edge cases, default behavior, rates, or requirements. It is minimally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: a single sentence that front-loads the core action and key options. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 4 optional parameters and no output schema, the description fails to indicate return structure (e.g., whether pagination metadata is included). Among 23 sibling tools, it lacks differentiation hints. This is insufficient for reliable agent selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with each parameter well-documented (e.g., tags note intersection, type is an enum). The description adds no additional meaning beyond the schema; a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists stored memories with optional filters and pagination. It avoids tautology and specifies the resource and actions, though it does not explicitly differentiate from siblings like search_memories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., search_memories for text search, get_memory for a single memory). The description does not include when-not conditions or context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every active rule memory with severity, scope, and staleness markers (>90 days since last_verified). Use this to audit which rules are currently constraining the agent.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It implicitly indicates read-only behavior by saying 'list' and mentions staleness markers. Could explicitly state non-destructive, but current description is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. Front-loaded with purpose and immediately provides use case. Excellent structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description explains return fields (severity, scope, staleness). Does not mention ordering or pagination, but for a list of active rules, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. Description adds no parameter info (unnecessary) but meets the baseline for a zero-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool lists active rule memories with specific fields (severity, scope, staleness). Differentiates from siblings like list_memories by specifying 'rule memory' and the staleness marker.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context by stating the tool is used for auditing rules that constrain the agent. Does not include explicit when-not-to-use or alternatives, but the use case is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read recent entries from the audit event log (.events.jsonl). Returns the last N events, optionally filtered by action.
| Name | Required | Description | Default |
|---|---|---|---|
| tail | No | How many recent events to return (default 20) | |
| action | No | Filter by action (save | delete | restore) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It correctly identifies the operation as a read, but does not disclose potential side effects, rate limits, or behavior when the log is empty. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that conveys the essential information without any unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with two parameters and no output schema, the description covers the core functionality. It could be improved by specifying return format or behavioral notes, but it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%. The description adds minimal new meaning beyond the schema, mainly rephrasing 'returns the last N events' and 'optionally filtered by action'. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read recent entries from the audit event log (.events.jsonl)' with a specific verb and resource, but does not differentiate from the sibling tool 'audit' which may have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like audit or other event-related tools. The description only states the basic function without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find memories relevant to a query and return their FULL content (not summaries). Designed for LLM ingestion — call this when the assistant needs context on a topic and the memory index alone isn't specific enough. Returns up to max memories as a markdown document.
| Name | Required | Description | Default |
|---|---|---|---|
| max | No | Max memories to include (default 5, capped at 20). | |
| query | Yes | The topic the assistant needs context on. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description fully responsible. Covers key behavior (returns full content as markdown, respects max cap). Does not disclose potential side effects, auth needs, or error conditions, but as a read-only tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no wasted words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description adequately explains return format (markdown document). Mention of 'memory index' context and distinction from summaries helps agent choose among sibling tools. Minor gap: no mention of empty results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds context: query is 'topic for context', max is 'capped at 20', result is 'full content as markdown' – improving understanding beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Find') and resource ('memories'), and explicitly distinguishes from siblings by emphasizing FULL content vs summaries, and LLM ingestion context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly states when to call ('when the assistant needs context on a topic and the memory index alone isn't specific enough'), implying when not to use. Lacks explicit sibling alternative but guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore a memory from .trash/ back into the active store. Picks the most recent trash entry for the name.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The memory's name slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden. It discloses the selection logic ('picks the most recent trash entry'), but does not mention error conditions, side effects (e.g., removal from trash), or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. Essential information is front-loaded. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 param, no output schema, no annotations), the description is adequately complete. It explains the operation, source/destination, and selection rule. Missing return value description, but acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes 'name' as 'The memory's name slug'. The description adds context about multiple trash entries and selection of most recent, providing value beyond the schema. Schema coverage is 100%, baseline 3, plus extra context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (restore a memory), the source (.trash/), and the destination (active store). It distinguishes from siblings like delete_memory and save_memory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for undeleting memories, but does not explicitly state when to use versus alternatives like delete_memory or save_memory. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rotate the receipt-signing key material (HMAC and/or Ed25519). Generates fresh keys and INVALIDATES every outstanding Compliance Receipt. Use after a suspected key leak — e.g. the .keyring was ever committed or synced. Optional mode: 'hmac' | 'ed25519' | 'both' (default 'both').
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Which key(s) to rotate. Default 'both'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: generates fresh keys and invalidates all outstanding Compliance Receipts. Since annotations are absent, the description carries full burden. It does not mention prerequisites or permissions, but the core behavioral traits are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence plus a clarification on mode. Every sentence provides necessary information with no fluff. Front-loaded with action and consequence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (1 param, no output schema), the description covers the essential behavioral aspects. However, it could mention the return value or whether the tool requires special permissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the only parameter 'mode'. The description restates the enum values and default, adding no extra meaning beyond the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool rotates receipt-signing key material (HMAC and/or Ed25519) and invalidates all outstanding Compliance Receipts. It uses specific verb 'rotate' and resource 'receipt-signing key material', distinguishing it from sibling tools which are memory/data operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use: 'Use after a suspected key leak — e.g. the .keyring was ever committed or synced.' It explains the consequence (invalidates all receipts) but does not explicitly state when not to use or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save (or update) a memory. Memories are markdown files with YAML frontmatter, stored at the resolved memory dir. Use a short kebab-case name; the description is what's shown in the index and used for search ranking.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Short kebab-case slug, 1-80 chars (e.g. 'user-prefers-tabs') | |
| tags | No | Optional tags for cross-cutting categorization. Lowercase, kebab/underscore, max 40 chars each. Queryable in list_memories + search_memories. | |
| type | Yes | Memory type: user (about the person), feedback (lessons + corrections), project (state/context), reference (external pointers), rule (constraint enforced via companion files — prefer the save_rule tool which validates rule-specific fields) | |
| content | Yes | Markdown body. For feedback/project, include **Why:** and **How to apply:** lines. | |
| description | Yes | One-line summary, shown in the index and ranked highly in search |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains that memories are markdown files with YAML frontmatter and gives naming conventions. It implies idempotency by stating 'Save (or update)'. Without annotations, the description carries some burden, but it omits details like permissions, rate limits, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. First sentence states the tool's action and file format, second gives key naming/index guidance. Information is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 5 parameters, no annotations, and no output schema, the description covers the core behavior but lacks details on idempotency, error handling, or return value. The schema is well-documented but the description could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that the 'name' should be kebab-case and the 'description' is used for indexing and search ranking, which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Save (or update) a memory' and explains what memories are. However, it does not explicitly differentiate from the sibling tool 'save_rule', though the schema includes that hint. The purpose is specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like save_rule. The usage hint for rule types is only in the parameter schema, not in the main description, so the agent lacks direct guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save (or update) a rule memory · the 'memory as constraint' wedge. Rules constrain agent behavior, not just store facts. Severity 'hard' = must obey; 'soft' = prefer to obey. Rules auto-project out to AGENTS.md (read by Claude Code, Codex CLI, Cursor, Aider, Devin, Copilot, Gemini CLI, Windsurf, and Amazon Q natively) when AGENT_MEMORY_AUTO_EMIT_DIR is set, or via the emit_companions tool on demand.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Short kebab-case slug, 1-80 chars (e.g. 'no-emojis-ever', 'tests-before-commit') | |
| scope | No | Where this rule applies. Examples: ['global'], ['project:prefixcheck'], ['tool:git']. | |
| content | Yes | Markdown body. Lead with the rule itself, then **Why:** and **How to apply:** lines. | |
| matches | No | Regex patterns that deterministically signal a violation. Used by Tier-1 check_action on every client. | |
| severity | No | hard = must obey (rule violations are blocked when enforced); soft = prefer to obey (warned but allowed). Defaults to soft. | |
| enforce_on | No | Action categories this rule constrains. Examples: 'file_writes', 'commits', 'pushes', 'chat_responses'. | |
| description | Yes | One-line summary of what the rule constrains | |
| applies_when | No | Natural-language conditions for when the rule triggers. Used by Sampling-enriched check_action on supporting clients. | |
| last_verified | No | ISO date (YYYY-MM-DD) of last verification. Defaults to today. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses severity levels and auto-projection behavior, but lacks details on authorization, rate limits, idempotency, or side effects of updating existing rules.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences, front-loaded with the core action. Each sentence earns its place: purpose, distinction, severity, projection. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the core purpose and key behaviors, but lacks information about return values (no output schema) and does not explain all parameters' use in depth. It is adequate but leaves gaps for an AI agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds value by explaining severity meaning and projection behavior, offering context beyond enum descriptions. It reinforces the purpose of each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Save (or update) a rule memory' with specific verb and resource. It distinguishes rules from factual memories ('constrain agent behavior, not just store facts'), and mentions unique auto-projection behavior, setting it apart from siblings like save_memory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly contrasts with factual memories ('not just store facts'), guiding when to use this tool. However, it does not explicitly list alternatives or state when not to use it, though the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fuzzy search across name, description, and body. Tolerates typos, word-order shifts, and partial matches. Returns top matches with relevance scores (0-100) and body-context snippets. Use this for human-readable browsing.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return (default 10). | |
| query | Yes | What to look for. Fuzzy match (typo-tolerant). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses key behaviors: fuzzy matching, typo tolerance, word-order shifts, and returns relevance scores with snippets. Since no annotations exist, the description carries the burden well. However, does not explicitly state read-only nature or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: first states purpose, second adds matching details, third explains use case. No redundant words; every sentence contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter tool with no output schema, the description adequately covers search behavior and output format (scores, snippets). Minor omission: does not explicitly confirm the tool is read-only, but given the search context, this is implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds value by clarifying that the query parameter supports fuzzy/typo-tolerant matching, and that limit has a default of 10. This enhances schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly defines the tool as performing fuzzy search across name, description, and body, with typo tolerance and partial matching. This purpose is distinct from sibling tools like 'list_memories' (listing) and 'get_memory' (exact retrieval).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Use this for human-readable browsing' provides a clear context for when to use the tool. Implicitly contrasts with other tools (e.g., exact search or verification) but does not explicitly list alternatives or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dashboard of memory-store state: counts per type, total size, largest memory, audit-log size, trash count.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose side effects, permissions, or output schema; only lists return fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key information, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple stats tool with no output schema, the description covers return types adequately; could mention if data is cached or live.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist (schema coverage 100%), so description need not add parameter info; baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a dashboard providing state metrics (counts, sizes, trash count), which distinguishes it from sibling tools like audit or get_memory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives; usage is implied as an overview, but no when-not or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pull memory updates from the configured git remote (fast-forward only). Run at the start of a session to get memories saved on other machines. Refuses to pull if there are uncommitted local changes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: fast-forward only, refusal on uncommitted changes. Without annotations, this covers the main behavioral traits adequately for a simple pull operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, front-loaded with actionable information. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description fully covers behavior, constraints, and usage context. Complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is trivially 100%. Description adds no param info but baseline is 4 per guidance for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool pulls memory updates from a configured git remote (fast-forward only), which distinguishes it from siblings like sync_push and sync_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises running at the start of a session to fetch memories from other machines, and notes the constraint about uncommitted local changes. Lacks explicit comparison to alternatives but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Commit any local memory changes and push to the configured git remote. Auto-generates a timestamped commit message if none provided. Use at the end of a session to make memories available on your other machines.
| Name | Required | Description | Default |
|---|---|---|---|
| message | No | Optional commit message. Defaults to a timestamp. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must convey behavior. Mentions auto-generated commit message if none provided, but fails to disclose failure modes (e.g., conflicts, authentication issues) or whether it force pushes. For a sync operation, these are important behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action, no extraneous words. Every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter, the description covers purpose and usage. However, it lacks details on error handling, remote status, or prerequisites, which would improve completeness for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. Description adds value by explaining the auto-generation of a timestamped commit message when 'message' is omitted, which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Commit... and push' and resource 'local memory changes' to 'configured git remote'. Distinguishes from sibling tools like sync_pull by specifying end-of-session usage and cross-machine availability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'at the end of a session to make memories available on your other machines.' Does not explicitly mention when not to use or alternatives, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report the git-sync state of the memory store: remote URL, branch, local uncommitted files, commits ahead/behind origin. Use this before opening a new session to know if you have stale memories from another machine.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description conveys a read-only status report without side effects. Could explicitly state non-destructive behavior, but the context strongly implies it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. First sentence lists outputs, second gives usage guidance. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description lists relevant fields and usage context. Lacks specifics on format or exact naming, but sufficient for a simple status tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so baseline is 4. The description adds value by detailing the output fields (remote URL, branch, etc.), exceeding the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports git-sync state, listing specific fields (remote URL, branch, uncommitted files, commits ahead/behind). It is distinct from sibling tools like sync_push and sync_pull.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises usage 'before opening a new session to know if you have stale memories' and implies it is a read-only status check, not for performing sync actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a CRP 1.1 (Ed25519) Compliance Receipt issued by ANOTHER agent-memory server using that server's published public key — no shared secret (the federation primitive). Checks signature, expiry, and required caveats. Pass receipt (object or JSON string) and public_key (inline PEM or a file path; the issuer gets theirs via agent-memory export-pubkey).
| Name | Required | Description | Default |
|---|---|---|---|
| receipt | Yes | The Compliance Receipt to validate (object or JSON string). | |
| public_key | Yes | Issuer's Ed25519 public key · inline PEM or a file path. | |
| required_caveats | No | Caveats that must be present (each {type, value}). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It details the checks performed: signature, expiry, and required caveats. It also explains input flexibility (object/JSON string for receipt, inline PEM or file path for public key). This provides solid behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two well-structured sentences. First sentence covers purpose and context, second covers parameters. No wasted words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers input well but lacks any mention of output or return value. For a validation tool, an agent needs to know whether it returns a boolean, throws on failure, or returns details. This omission makes it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaning by stating receipt can be object or JSON string, public_key can be inline PEM or file path, and required_caveats is an array of {type, value}. This goes beyond the schema's bare descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it validates a CRP 1.1 Compliance Receipt using a public key. It specifies the resource (receipt), the action (validate), and the context (federation primitive). This uniquely distinguishes it from sibling tools like audit or verify_memory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool: to validate a receipt from another agent-memory server. It provides context that the public key comes from the issuer via export-pubkey. However, it does not explicitly list when not to use it or mention alternatives, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-evaluate a memory's claims against signals in its content. Extracts URLs, dates, and file paths from the body; flags stale-date signals on project-type memories; returns type-specific verification heuristics for the LLM or operator to act on. Pairs with the audit_stale prompt.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The memory's name slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses key behaviors (extraction, flagging stale dates) and states that it returns heuristics for LLM/operator action. However, it does not clarify if the tool modifies memory or has side effects, leaving some behavioral intent unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each serving a distinct purpose: stating the main action, listing specific extractions, and noting a paired prompt. It is efficient with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter schema and no output schema, the description adequately explains what the tool does and what it returns. It lacks details on return structure or example output, but the mention of 'verification heuristics' provides sufficient context for this level of complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'name' is documented in the schema with description 'The memory's name slug'. The tool description does not add any additional meaning or usage context for this parameter, so it meets the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: re-evaluate memory claims and extract signals like URLs, dates, and file paths. It differentiates from siblings like 'audit' by specifying it verifies memory-specific content, though it doesn't explicitly contrast with other verification tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions pairing with 'audit_stale prompt', implying a context of use, but does not provide explicit guidance on when to use this tool versus alternatives like 'check_action' or 'audit'. No when-not-to-use or exclusion criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.15.1auditcheck_actiondelete_memorydoctoremit_companionsfind_backlinksfind_relatedget_memoryinitlist_memorieslist_ruleslog_eventsrelevant_memoriesrestore_memoryrotate_keysave_memorysave_rulesearch_memoriesstatssync_pullsync_pushsync_statusvalidate_receiptverify_memoryEvery tool has a clearly distinct purpose. Even similar tools like search_memories vs relevant_memories are differentiated by output detail. Audit and doctor target different aspects (rule health vs storage integrity). No ambiguity.
Most tools follow verb_noun snake_case (save_rule, list_memories). A few are single-word verbs (audit, doctor, stats, init). This is a minor deviation but still predictable and readable.
24 tools is well-scoped for a memory server covering CRUD, rule enforcement, sync, health checks, and federation. Each tool earns its place; no unnecessary redundancy.
Core CRUD for memories and rules is covered, plus sync, health, and federation. A notable gap is the lack of a delete_rule tool; save_rule can update but not delete. Otherwise comprehensive.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Deterministic runtime safety for AI agents: scan PII, gate tool actions, verify LLM output.
Security gateway for AI agents: policy, approval, and audited execution, no secrets shared.
Governance layer for AI coding agents: knowledge-graph grounding, session audit, policy controls.
Pre-execution governance for AI agents. Deterministic PASS/FAIL/REVIEW verdicts, replayable proof.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/xultrax-web/agent-memory-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
