Recall Memory
recall_memoryRecall memories from AutoMem in one of three modes. The mode is selected by which params you pass.
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; next page at next_offset. 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_entitiesfor 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: "8f3a2c1e-5b7d-4e9a-a1c3-2d4f6b8e0a91" }) // 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
| 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. When omitted, the server defaults to 5 in ranked mode and 20 in enumeration mode. | |
| 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, in `results` order, then one bracketed trailing block when there are notes or budget cuts), 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 | Enumeration mode only (`exhaustive: true`): records to skip, for paging. Ranked recall has no offset and rejects one; raise `limit` instead. | |
| 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 | "prefix" (ranked default) matches tags that start with the value, so `tags: ["automem"]` also matches `automem-evals`; "exact" matches whole tags only. Enumeration mode is always exact. | |
| 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
| Name | Required | Description | Default |
|---|---|---|---|
| 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 of this response. When the response budget trims a page, `count` and `limit` shrink to the results returned, so `offset + limit` still starts the next page. | |
| 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 records exist past this page. Continue at `next_offset`. | |
| 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 the response budget cut anything: { applied, omitted_results, reason }, plus `omitted_fields` (diagnostics dropped because they did not fit even without results) and `compacted_results` (a json result shown in compact form because it did not fit whole). | |
| next_offset | No | Enumeration mode only, when `has_more` is true: the `offset` for the next page (this offset plus the results returned). | |
| 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. |