Complete reference for all 53 Agent Memory MCP tools — core recall and save, orchestration, team sharing, knowledge graph, lessons, slots, and more.
Agent Memory exposes up to 53 tools via the Model Context Protocol. Your AI agent calls these automatically based on context, or you can invoke them directly by name. Use the AGENTMEMORY_TOOLS environment variable to control which tools are visible to your agent.
The @agentmemory/mcp shim exposes the full 53-tool surface only when it can reach a running agentmemory server via AGENTMEMORY_URL. Without a server, it falls back to 7 local tools. If you see fewer tools than expected, make sure npx @agentmemory/agentmemory is running and AGENTMEMORY_URL=http://localhost:3111 is set.
Set AGENTMEMORY_TOOLS=core to expose only the 8 essential tools. Recommended for agents with limited context windows that struggle with a large tool list.
All Mode (default)
The default AGENTMEMORY_TOOLS=all exposes all 53 tools across every capability tier: search, orchestration, team sharing, knowledge graph, lessons, and more.
If your agent is hitting context-window limits or behaving erratically with too many tools, set AGENTMEMORY_TOOLS=core in your ~/.agentmemory/.env file and restart the server.
These tools are always available regardless of the AGENTMEMORY_TOOLS setting. They cover the essential read/write/search lifecycle every agent needs.
Tool
Description
memory_recall
Search past session observations by keyword, file name, or concept. Accepts an optional format of full, compact, or narrative and a token_budget to trim results.
memory_save
Explicitly save an insight, decision, or fact to long-term memory. Accepts type (pattern, preference, architecture, bug, workflow, fact), concepts, and files metadata.
memory_smart_search
Hybrid BM25 + vector + graph search with progressive disclosure. Pass expandIds to drill into specific results. The most powerful retrieval tool.
memory_file_history
Get all past observations about one or more specific files. Pass a comma-separated list of file paths.
memory_patterns
Detect recurring patterns across sessions for a project — frequently touched files, repeated errors, workflow habits.
memory_sessions
List all recorded sessions with their status and observation counts.
memory_timeline
Return chronological observations around a point in time. Pass an ISO date or keyword as the anchor, and control how many items appear before and after it.
memory_profile
Get a project profile: top concepts, most-accessed files, learned conventions, and recurring patterns.
memory_export
Export all memory data as a JSON snapshot. Useful for backup or migration.
memory_relations
Traverse the memory relationship graph starting from a memoryId. Controls maxHops (default 2) and minConfidence threshold.
memory_compress_file
Compress a Markdown file to reduce token usage while preserving headings, URLs, and code blocks. Creates a .original.md backup first.
memory_commit_lookup
Look up which agent session(s) produced a specific git commit by its full SHA.
memory_commits
List recent git commits linked to agent sessions, optionally filtered by branch or remote URL.
memory_vision_search
Cross-modal image search via CLIP embeddings. Requires AGENTMEMORY_IMAGE_EMBEDDINGS=true. See Snapshots, Vision & Integrations for full parameter details.
Manually trigger the 4-tier consolidation pipeline (working → episodic → semantic → procedural). Pass an optional tier to target a specific stage. Requires CONSOLIDATION_ENABLED=true.
memory_diagnose
Run self-diagnostics across all subsystems — actions, leases, sentinels, sketches, signals, sessions, memories, and mesh peers. Identifies stuck, orphaned, and inconsistent state.
memory_heal
Auto-repair all fixable issues found by diagnostics. Unblocks stuck actions, expires stale leases, and cleans up orphaned data. Supports dryRun=true to preview changes first.
These tools require GRAPH_EXTRACTION_ENABLED=true in your config. With graph extraction on, agentmemory automatically builds an entity relationship graph from your session observations.
Tool
Description
memory_graph_query
Traverse the knowledge graph by entity or relationship type. Pass startNodeId for BFS traversal, nodeType to filter, or query to search nodes by name. Supports maxDepth up to 8.
Orchestration tools are available in v0.5 and later. They power multi-agent task coordination: creating work items, claiming exclusive leases, sending inter-agent messages, and managing approval gates.
Actions
Routines & Sketches
Signals & Gates
Create and track actionable work items with typed dependency graphs.
Tool
Description
memory_action_create
Create an actionable work item with a title, description, priority (1–10), and optional requires dependencies (comma-separated action IDs). Supports hierarchical parent/child via parentId.
memory_action_update
Update an action’s status (pending, active, done, blocked, cancelled), priority, or result. Setting status=done automatically unblocks dependent actions.
memory_frontier
Get all currently unblocked actions ranked by priority and urgency — the full set of work your agent can pick up right now.
memory_next
Get the single most important next action. Combines dependency resolution, priority, and recency into one score and returns the winner.
memory_lease
Acquire, release, or renew an exclusive lock on an action. Prevents multiple agents from working on the same item simultaneously. Supports ttlMs up to 1 hour.
Manage reusable workflow templates and exploratory work graphs.
Tool
Description
memory_routine_run
Instantiate a frozen workflow template as a chain of actions with proper dependencies already wired. Pass routineId to identify the template.
memory_sketch_create
Create an ephemeral exploratory action graph with a TTL (default 1 hour). Use it to plan work before committing.
memory_sketch_promote
Promote a sketch’s ephemeral actions to permanent actions, making the exploratory work official.
memory_crystallize
Compress completed action chains into a compact digest using LLM summarization. Extracts narrative, key outcomes, affected files, and lessons learned.
Agent-to-agent messaging and external condition gates.
Tool
Description
memory_signal_send
Send a message from one agent to another (or broadcast). Supports message type (info, request, response, alert, handoff), threading via replyTo, and TTL expiration.
memory_signal_read
Read incoming messages for an agent. Marks delivered messages as read. Filter by unreadOnly or threadId.
memory_checkpoint
Create (operation=create), resolve (operation=resolve), or list (operation=list) external gates — CI results, approvals, or deploy statuses — that block action progress until cleared.
memory_sentinel_create
Create an event-driven watcher that monitors for conditions (webhook, timer, threshold, pattern, approval, custom) and auto-unblocks gated actions when triggered.
memory_sentinel_trigger
Manually fire a sentinel, providing an optional JSON result payload. Immediately unblocks any actions the sentinel was gating.
These tools implement the confidence-scored learning layer — separate from raw memory, lessons track what your agent has explicitly learned and how certain it is.
Tool
Description
memory_lesson_save
Save a lesson learned from a session. Lessons carry a confidence score (0.0–1.0, default 0.5) that strengthens when reinforced and decays when unused. Duplicate content auto-strengthens the existing lesson instead of creating a duplicate.
memory_lesson_recall
Search lessons by query. Returns results sorted by confidence and recency. Use before making decisions to check what the agent already knows. Supports minConfidence filtering.
memory_reflect
Traverse the knowledge graph, group related memories into concept clusters, and synthesize higher-order insights via LLM. Returns new and reinforced insights from up to maxClusters groups (default 10).
memory_insight_list
List all synthesized insights — higher-order observations derived from patterns across memories, lessons, and crystallized action chains. Filter by minConfidence.
memory_obsidian_export
Export memories, lessons, and crystals as Obsidian-compatible Markdown files with YAML frontmatter and wikilinks for use in graph view.
Memory slots require AGENTMEMORY_SLOTS=true in your configuration. Slots are editable, size-limited memory units that persist across sessions and can be injected at session start.
Slots give your agent named, persistent storage units — think of them as structured notepads your agent can read and update in place. Default slot labels include persona, user_preferences, tool_guidelines, project_context, guidance, pending_items, session_patterns, and self_notes.
Tool
Description
memory_slot_list
List all memory slots (pinned, project-scoped, and global).
memory_slot_get
Read a single slot by label.
memory_slot_create
Create a new slot with a label, optional initial content, sizeLimit (default 2,000 chars, hard cap 20,000), and scope (project or global).
memory_slot_append
Append text to an existing slot. Returns an error if the append would exceed the slot’s size limit — compact first with memory_slot_replace.
memory_slot_replace
Replace a slot’s full content in place. Fails if the new content exceeds the size limit.
memory_slot_delete
Delete a slot. Default slots can be deleted unless marked readOnly.
Trace a memory or observation back through its citation chain to source observations and session context. Returns confidence scores and provenance metadata.
memory_facet_tag
Attach a structured dimension:value tag to an action, memory, or observation. Example: priority:urgent or team:backend.
memory_facet_query
Query targets by facet tags with AND (matchAll) or OR (matchAny) logic. Example: find all actions tagged priority:urgent AND team:backend.
Create a git-versioned snapshot of the current memory state with an optional commit message. Requires SNAPSHOT_ENABLED=true.
memory_vision_search
Cross-modal image search via CLIP embeddings. Pass queryText to find screenshots matching a description, or queryImageBase64 / queryImageRef to find visually similar images. Requires AGENTMEMORY_IMAGE_EMBEDDINGS=true.
memory_claude_bridge_sync
Bi-directionally sync memory state with Claude Code’s native MEMORY.md file. Pass direction=read to import from MEMORY.md, or direction=write to export to it. Requires CLAUDE_MEMORY_BRIDGE=true.
Agent Memory exposes 3 built-in prompts your agent can reference via the MCP prompts/get protocol. Prompts return pre-built message arrays you can inject directly into a conversation.
Prompt
Required Argument
Description
recall_context
task_description
Searches past observations and memories for a given task and returns a formatted context block ready to inject into the current session.
session_handoff
session_id
Produces a structured handoff summary for a specific session — useful when handing off work to a new agent instance or continuing in a new session.
detect_patterns
project (optional)
Analyzes sessions for a project and surfaces recurring patterns as a structured message.
Use the recall_context prompt with task_description="implement JWT refresh token rotation"
Claude will call the prompt, which searches your memory and returns relevant past decisions, file history, and observations — all pre-formatted as context for your task.
