retrieve_memories
The workhorse of Memory MCP. Every parameter is optional — combine them to narrow your search, or pass none to return the most recent memories.
Parameters #
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | No | Natural language search — retrieves by meaning, not keyword match |
labels | string | No | Comma-separated label filter. Substring-matched, case-insensitive. Prefix with ! to exclude |
source | string | No | Source filter. Substring-matched. Prefix with ! to exclude |
num_results | number | No | Maximum results to return (default: 5) |
Filtering Modes #
| Query | Labels | Source | Behaviour |
|---|---|---|---|
| ✅ | — | — | Semantic search across all memories |
| — | ✅ | — | Label filter, sorted by recency |
| — | — | ✅ | Source filter, sorted by recency |
| ✅ | ✅ | — | Semantic search within label-filtered memories |
| ✅ | — | ✅ | Semantic search within source-filtered memories |
| — | ✅ | ✅ | Label + source filter, sorted by recency |
| ✅ | ✅ | ✅ | Semantic search with label and source filters |
| — | — | — | Most recent N memories |
Examples #
# Semantic search
retrieve_memories(query: "what did we decide about authentication")
# Label filter — recent plugin dev memories, excluding cron noise
retrieve_memories(labels: "plugin-dev,!cron")
# Scoped to a specific agent
retrieve_memories(query: "database migration", source: "agent:sonnet:main")
# Most recent 10 memories
retrieve_memories(num_results: 10)
Power Combinations #
Trending wake-up — pair with trending_labels to surface thematically relevant recent memories without a query:
trending_labels(days: 7, limit: 10)
→ use top_tokens as label seeds →
retrieve_memories(labels: "memory,plugin,system", num_results: 5)
Agent isolation — retrieve only a specific agent’s memories:
retrieve_memories(source: "agent:sonnet:main", num_results: 10)
Topic archaeology — semantic + label to find old decisions on a topic:
retrieve_memories(query: "authentication approach", labels: "architecture", num_results: 10)