Agent Memory MCP Tools: Complete Reference (53 Tools)

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.

Tool Tiers

Core Mode

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.

Core Tools

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.

Essential Tools (the 8-tool `core` set)

When you set AGENTMEMORY_TOOLS=core, your agent sees only this subset — chosen for maximum utility at minimum context cost:

Tool	Why It’s Essential
`memory_save`	The primary write path
`memory_recall`	The primary read path
`memory_consolidate`	Keeps memory health high
`memory_smart_search`	Best retrieval for ambiguous queries
`memory_sessions`	Session situational awareness
`memory_diagnose`	Self-service troubleshooting
`memory_lesson_save`	Captures confidence-weighted learnings
`memory_reflect`	Synthesizes higher-order insights

Memory Consolidation & Health

Tool	Description
`memory_consolidate`	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.

Knowledge Graph Tools

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.

Team & Collaboration Tools

Team tools require TEAM_ID and USER_ID to be set in your configuration. Without them, calls return a prompt to configure team mode.

Tool	Description
`memory_team_share`	Share a memory or observation with your team. Pass the `itemId` and `itemType` (`observation`, `memory`, or `pattern`).
`memory_team_feed`	Get recent memories shared by all team members. Returns up to `limit` items (default 20).
`memory_audit`	View the full audit trail of memory operations. Filter by `operation` type and control the number of entries returned.
`memory_governance_delete`	Delete one or more memories by ID with a mandatory audit trail entry. Pass `reason` to document why.
`memory_mesh_sync`	Sync memories and actions with peer agentmemory instances for multi-agent collaboration. Supports `push`, `pull`, or `both` directions.

Orchestration Tools

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.

Lessons & Insights

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

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

Provenance & Tagging

Tool	Description
`memory_verify`	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`.

Snapshots, Vision & Integrations

Tool	Description
`memory_snapshot_create`	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`.

MCP Prompts

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.

Example: using a prompt in Claude Code

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.

​Tool Tiers

Core Mode

All Mode (default)

​Core Tools

​Essential Tools (the 8-tool core set)

​Memory Consolidation & Health

​Knowledge Graph Tools

​Team & Collaboration Tools

​Orchestration Tools

​Lessons & Insights

​Memory Slots

​Provenance & Tagging

​Snapshots, Vision & Integrations

​MCP Prompts

​Example: using a prompt in Claude Code

Tool Tiers

Core Tools

Essential Tools (the 8-tool `core` set)

Memory Consolidation & Health

Knowledge Graph Tools

Team & Collaboration Tools

Orchestration Tools

Lessons & Insights

Memory Slots

Provenance & Tagging

Snapshots, Vision & Integrations

MCP Prompts

Example: using a prompt in Claude Code