> ## Documentation Index
> Fetch the complete documentation index at: https://agent-memory.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Memory MCP Tools: Complete Reference (53 Tools)
> 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.
## Tool Tiers
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.
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](#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.
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
```text theme={null}
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.