mcp-automem

Recall Memory

recall_memory

Read-onlyIdempotent

Retrieve relevant past memories stored in AutoMem using semantic search, tag filtering, or exact memory ID. Use it to recall project context, past decisions, and solutions to similar problems before acting.

Instructions

Recall memories from AutoMem in one of three modes. The mode is selected by which params you pass.

Mode 1 — ID fetch: pass memory_id to retrieve a single memory by ID. All other params are ignored. Routes to GET /memory/{id} and updates last_accessed.

Mode 2 — Tag enumeration: pass tags + exhaustive: true for paginated exact-match listing (NOT ranked retrieval). Use this for cleanup/audit workflows where ranked retrieval silently undercounts large tag sets. Pair with limit (≤200) and offset. Returns has_more/limit/offset page metadata. Tag matching is exact, case-insensitive, any-of mode — tag_match: "prefix" and tag_mode: "all" are rejected in this mode.

Mode 3 — Ranked retrieval (default): hybrid search across vector, keyword, tags, recency, and optional graph expansion. The primary tool for finding relevant context. By default, ranked recall requests current active memories only; set current_only: false for audits.

When to use ranked (mode 3):

At conversation start: recall context about the current project/topic
Before making decisions: check for past decisions on similar topics
When debugging: search for similar past errors and their solutions
For complex questions: use expand_entities for multi-hop reasoning

When to use enumeration (mode 2): when you need to know how many memories carry a tag, or to walk all of them for cleanup/migration. Ranked recall ignores low-importance hits — enumeration does not.

Examples:

recall_memory({ query: "database architecture decisions", tags: ["my-project"], limit: 5 })
recall_memory({ memory_id: "abc123" }) // Mode 1
recall_memory({ tags: ["benchmark-test"], exhaustive: true, limit: 50 }) // Mode 2 (add offset for later pages)
recall_memory({ query: "auth", exclude_tags: ["deprecated"] }) // Mode 3 with exclusion
recall_memory({ query: "What is Sarah's sister's job?", expand_entities: true }) // Mode 3 multi-hop

Input Schema

TableJSON Schema

Name	Required	Description	Default
`end`	No	ISO timestamp upper bound
`sort`	No	Result ordering (use time_* for chronological recaps)
`tags`	No	Filter by tags. Use project name as first tag for scoping.
`limit`	No	Max memories to return. Schema allows 1–200; in enumeration mode (`exhaustive: true`) the server honors up to 200, while ranked mode is typically clamped server-side to ~50. Default 5.
`query`	No	Semantic search query (natural language). Describe what you're looking for.
`start`	No	ISO timestamp lower bound (alternative to time_query)
`format`	No	Output format: text (default), items (one block per memory), detailed (adds type/confidence/metadata keys/relation stubs), json (raw per-memory fields incl. full content/metadata/relations; whole-response token budget still applies). text/items/detailed show a content preview (default 400 chars) and keep any stored summary as an additive field — fetch a full record via memory_id.	text
`offset`	No	Result offset for pagination
`context`	No	Context label (e.g., "coding-style", "architecture"). Boosts matching preferences.
`queries`	No	Multiple queries for broader recall. Results are deduplicated server-side.
`language`	No	Programming language hint (e.g., "python", "typescript"). Prioritizes language-specific memories.
`tag_mode`	No	"any" matches memories with any tag (default), "all" requires all tags
`embedding`	No	Optional embedding vector for direct similarity search
`memory_id`	No	MODE: ID fetch. When set, fetches the single memory by ID and IGNORES all other params. Routes to GET /memory/{id}; updates last_accessed.
`min_score`	No	Ranked-mode only. Minimum final score threshold before results are returned.
`tag_match`	No	"exact" for exact tag match (default), "prefix" for starts-with matching
`exhaustive`	No	MODE: tag enumeration. When true, requires non-empty `tags`. Routes to GET /memory/by-tag for paginated exact-match listing — NOT ranked retrieval. Use for cleanup/audit workflows where ranked recall undercounts. `limit` is clamped to 200. `tag_match: "prefix"` and `tag_mode: "all"` are rejected in this mode.
`state_mode`	No	Ranked-mode only. `current` returns active memories; `history` allows superseded/invalidated memories for audit timelines. Prefer this over current_only for new clients.
`time_query`	No	Natural language time filter: "today", "yesterday", "last week", "last 30 days"
`active_path`	No	Current file path for language auto-detection (e.g., "src/auth.ts")
`state_debug`	No	Ranked-mode only. Include state-filter suppression/replacement IDs and reasons when current_only is true.
`context_tags`	No	Priority tags to boost in results (e.g., ["coding-style", "preferences"])
`current_only`	No	Ranked-mode only. When true, server suppresses archived, not-yet-valid, expired, invalidated, or superseded memories from active context.
`exclude_tags`	No	Ranked-mode only. Tags to exclude from results (any match excludes). Independent of `tag_match` — supports both exact and prefix matching internally on the server.
`priority_ids`	No	Specific memory IDs to ensure are included in results
`recency_bias`	No	Ranked-mode only. Controls service recency boosting: auto lets the service infer, on forces boosting, off disables it.
`context_types`	No	Priority memory types to boost (e.g., ["Style", "Preference"])
`adaptive_floor`	No	Ranked-mode only. Enable the service's adaptive score floor when filtering weak matches.
`auto_decompose`	No	Auto-extract entities and topics from query to generate supplementary searches.
`relation_limit`	No	Max relations to follow per seed memory (default: 5)
`scope_fallback`	No	Ranked-mode only. Allow fallback outside the requested tag scope when scoped recall has weak evidence; diagnostics report tag_scope and outside_tag_scope.
`expand_entities`	No	Enable multi-hop reasoning via entity expansion. Finds memories about people/places mentioned in seed results. Use for "What is X's sister's job?" type questions.
`expansion_limit`	No	Max total expanded memories (default: 25)
`per_query_limit`	No	Per-query result limit when using queries[] (default: 5)
`expand_relations`	No	Follow graph relationships from seed results to find related memories.
`expand_min_strength`	No	Minimum relation strength to follow during graph expansion. Only traverses edges above this threshold. Recommended: 0.3 for exploratory, 0.6+ for high-confidence connections only. Does not affect entity expansion.
`expand_respect_tags`	No	Ranked-mode only. When true, graph/entity expansion stays within the original tag scope; when false, expansion may include related context outside the tags.
`expand_min_importance`	No	Minimum importance score for expanded results. Filters out low-relevance memories during graph/entity expansion. Recommended: 0.3-0.5 for broad context, 0.6-0.8 for focused results. Seed results are never filtered, only expanded ones.

Output Schema

TableJSON Schema

Name	Required	Description
`mode`	No	Mode that produced the result.
`sort`	No	Sort mode applied by the service.
`count`	Yes	Number of memories returned
`limit`	No	Enumeration mode only: page size used for this response.
`query`	No	Query text executed by ranked recall.
`offset`	No	Enumeration mode only: offset used for this response.
`queries`	No	Query variants executed by the service.
`results`	Yes	Array of matching memories with scores
`entities`	No	Entity identity diagnostics injected by the service.
`has_more`	No	Enumeration mode only: true if more pages exist past `offset + limit`.
`tag_scope`	No	Tag-scope diagnostics including whether scoped evidence was strong enough.
`state_mode`	No	State mode applied by ranked recall.
`truncation`	No	Present when trailing results were dropped to fit the response budget: { applied, omitted_results, reason }.
`exclude_tags`	No	Tags excluded from ranked recall.
`recency_bias`	No	Recency bias mode applied by the service.
`score_filter`	No	Score filtering diagnostics such as min_score, adaptive_floor, and filtered_count.
`state_filter`	No	Current-state filtering diagnostics. Includes aggregate counts by default and detailed IDs/reasons only when state_debug=true.
`dedup_removed`	No	Number of duplicate results removed (when using multiple queries)
`query_time_ms`	No	Service recall latency in milliseconds.
`vector_search`	No	Vector-search diagnostics from the service.
`scope_fallback`	No	True when recall allowed outside-scope fallback results.
`jit_enriched_count`	No	Number of memories enriched inline during recall.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.14.2Aug 26, 2026

changedInput schema / properties / format / description

Previous value: -"Output format: text (default), items (one block per memory), detailed (adds type/confidence/metadata keys/relation stubs), json (raw per-memory fields incl. full content/metadata/relations; whole-response token budget still applies). text/items/detailed are summary-first: each memory shows its stored 1-2 sentence summary when available, else a content preview — fetch a full record via memory_id."New value: +"Output format: text (default), items (one block per memory), detailed (adds type/confidence/metadata keys/relation stubs), json (raw per-memory fields incl. full content/metadata/relations; whole-response token budget still applies). text/items/detailed show a content preview (default 400 chars) and keep any stored summary as an additive field — fetch a full record via memory_id."

changedOutput schema / properties / results / items / properties / content / description

Previous value: -"Memory content (preview in budgeted formats; omitted when summary is shown)."New value: +"Memory content (preview-capped in budgeted formats)."

changedOutput schema / properties / results / items / properties / content_chars / description

Previous value: -"Original content length when content was previewed or replaced by summary."New value: +"Original content length when content was previewed."

changedOutput schema / properties / results / items / properties / summary / description

Previous value: -"Stored 1-2 sentence summary. In budgeted formats it replaces content when present."New value: +"Stored 1-2 sentence summary when the server provides one. Additive in budgeted formats; does not replace content."

Changed33 schema fields changedv0.14.1Jun 28, 2026

addedInput schema / properties / adaptive_floor

Added value: +{
+  "description": "Ranked-mode only. Enable the service's adaptive score floor when filtering weak matches.",
+  "type": "boolean"
+}

addedInput schema / properties / current_only

Added value: +{
+  "default": true,
+  "description": "Ranked-mode only. When true, server suppresses archived, not-yet-valid, expired, invalidated, or superseded memories from active context.",
+  "type": "boolean"
+}

addedInput schema / properties / expand_respect_tags

Added value: +{
+  "description": "Ranked-mode only. When true, graph/entity expansion stays within the original tag scope; when false, expansion may include related context outside the tags.",
+  "type": "boolean"
+}

changedInput schema / properties / format / description

Previous value: -"Output format: text (default), items (per-memory), detailed (with metadata), json (raw)"New value: +"Output format: text (default), items (one block per memory), detailed (adds type/confidence/metadata keys/relation stubs), json (raw per-memory fields incl. full content/metadata/relations; whole-response token budget still applies). text/items/detailed are summary-first: each memory shows its stored 1-2 sentence summary when available, else a content preview — fetch a full record via memory_id."

addedInput schema / properties / min_score

Added value: +{
+  "description": "Ranked-mode only. Minimum final score threshold before results are returned.",
+  "maximum": 1,
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / recency_bias

Added value: +{
+  "description": "Ranked-mode only. Controls service recency boosting: auto lets the service infer, on forces boosting, off disables it.",
+  "enum": [
+    "auto",
+    "on",
+    "off"
+  ],
+  "type": "string"
+}

addedInput schema / properties / scope_fallback

Added value: +{
+  "description": "Ranked-mode only. Allow fallback outside the requested tag scope when scoped recall has weak evidence; diagnostics report tag_scope and outside_tag_scope.",
+  "type": "boolean"
+}

addedInput schema / properties / state_debug

Added value: +{
+  "default": false,
+  "description": "Ranked-mode only. Include state-filter suppression/replacement IDs and reasons when current_only is true.",
+  "type": "boolean"
+}

addedInput schema / properties / state_mode

Added value: +{
+  "description": "Ranked-mode only. `current` returns active memories; `history` allows superseded/invalidated memories for audit timelines. Prefer this over current_only for new clients.",
+  "enum": [
+    "current",
+    "history"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / entities

Added value: +{
+  "description": "Entity identity diagnostics injected by the service.",
+  "items": {
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / exclude_tags

Added value: +{
+  "description": "Tags excluded from ranked recall.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / jit_enriched_count

Added value: +{
+  "description": "Number of memories enriched inline during recall.",
+  "type": "integer"
+}

addedOutput schema / properties / queries

Added value: +{
+  "description": "Query variants executed by the service.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / query

Added value: +{
+  "description": "Query text executed by ranked recall.",
+  "type": "string"
+}

addedOutput schema / properties / query_time_ms

Added value: +{
+  "description": "Service recall latency in milliseconds.",
+  "type": "number"
+}

addedOutput schema / properties / recency_bias

Added value: +{
+  "description": "Recency bias mode applied by the service.",
+  "enum": [
+    "auto",
+    "on",
+    "off"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / results / items / properties / content / description

Added value: +"Memory content (preview in budgeted formats; omitted when summary is shown)."

addedOutput schema / properties / results / items / properties / content_chars

Added value: +{
+  "description": "Original content length when content was previewed or replaced by summary.",
+  "type": "integer"
+}

addedOutput schema / properties / results / items / properties / content_truncated

Added value: +{
+  "description": "True when content is a preview; fetch the full record via recall_memory({ memory_id }).",
+  "type": "boolean"
+}

addedOutput schema / properties / results / items / properties / deduped_from

Added value: +{
+  "description": "Result IDs merged into this result during multi-query deduplication.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / results / items / properties / jit_enriched

Added value: +{
+  "description": "True when the service enriched the memory during recall.",
+  "type": "boolean"
+}

addedOutput schema / properties / results / items / properties / outside_tag_scope

Added value: +{
+  "description": "True when scope_fallback admitted this result outside the requested tag scope.",
+  "type": "boolean"
+}

addedOutput schema / properties / results / items / properties / state_replaces

Added value: +{
+  "description": "ID of the suppressed memory this result replaced during current-state filtering.",
+  "type": "string"
+}

addedOutput schema / properties / results / items / properties / summary

Added value: +{
+  "description": "Stored 1-2 sentence summary. In budgeted formats it replaces content when present.",
+  "type": "string"
+}

addedOutput schema / properties / results / items / properties / updated_at
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / scope_fallback

Added value: +{
+  "description": "True when recall allowed outside-scope fallback results.",
+  "type": "boolean"
+}

addedOutput schema / properties / score_filter

Added value: +{
+  "description": "Score filtering diagnostics such as min_score, adaptive_floor, and filtered_count.",
+  "type": "object"
+}

addedOutput schema / properties / sort

Added value: +{
+  "description": "Sort mode applied by the service.",
+  "type": "string"
+}

addedOutput schema / properties / state_filter

Added value: +{
+  "description": "Current-state filtering diagnostics. Includes aggregate counts by default and detailed IDs/reasons only when state_debug=true.",
+  "type": "object"
+}

addedOutput schema / properties / state_mode

Added value: +{
+  "description": "State mode applied by ranked recall.",
+  "enum": [
+    "current",
+    "history"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / tag_scope

Added value: +{
+  "description": "Tag-scope diagnostics including whether scoped evidence was strong enough.",
+  "type": "object"
+}

addedOutput schema / properties / truncation

Added value: +{
+  "description": "Present when trailing results were dropped to fit the response budget: { applied, omitted_results, reason }.",
+  "type": "object"
+}

addedOutput schema / properties / vector_search

Added value: +{
+  "description": "Vector-search diagnostics from the service.",
+  "type": "object"
+}

First observedv0.14.0May 26, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds valuable behavioral detail beyond that: ID fetch routes to GET /memory/{id} and updates last_accessed, enumeration uses paginated exact-match listing, ranked mode clamps server-side to ~50 results, and mode-specific options are rejected. There is no contradiction with the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but appropriately structured for a tool with 38 parameters and three modes: it front-loads the mode-selection rule, uses clear headers, gives explicit when-to-use bullets, and ends with examples. Minor redundancy exists, such as repeating the cleanup/audit rationale in both Mode 2 and the usage section, but the overall organization is efficient for the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 38 parameters, a rich schema, and an output schema, the description covers the decision space comprehensively: it explains all three modes, which params are ignored or rejected, pagination metadata, output format options, and when each mode is appropriate. The examples cover representative calls for each mode, and nothing critical for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3; the description still adds value by explaining how parameters select modes, how limit behaves differently in enumeration vs ranked mode, and by showing realistic parameter combinations in examples. It does not need to restate every schema field, and the mode-selection semantics go beyond what the schema alone conveys.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool recalls memories from AutoMem and immediately differentiates three distinct modes based on which parameters are passed. It names each mode, the route it uses, and the outcome, and provides concrete examples for every mode, so an agent cannot confuse this with sibling tools like store_memory or delete_memory.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: ranked retrieval for conversation start, decision-making, debugging, and multi-hop reasoning; tag enumeration when the agent needs exact counts or cleanup/audit walks. It also states exclusions such as 'NOT ranked retrieval' and which parameter combinations are rejected, leaving no ambiguity about mode selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server