Recall Memory
recall_memoryRetrieve relevant past memories from AutoMem using ID, tag enumeration, or ranked hybrid search. Supports semantic queries, tags, time filters, and multi-hop entity expansion.
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.
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: "abc123" }) // Mode 1
recall_memory({ tags: ["benchmark-test"], exhaustive: true, limit: 50 }) // Mode 2
recall_memory({ tags: ["benchmark-test"], exhaustive: true, limit: 50, offset: 50 }) // Mode 2 page 2
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 |
|---|---|---|---|
| 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. | |
| 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. | |
| 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. | |
| query | No | Semantic search query (natural language). Describe what you're looking for. | |
| queries | No | Multiple queries for broader recall. Results are deduplicated server-side. | |
| embedding | No | Optional embedding vector for direct similarity search | |
| 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. | |
| time_query | No | Natural language time filter: "today", "yesterday", "last week", "last 30 days" | |
| start | No | ISO timestamp lower bound (alternative to time_query) | |
| end | No | ISO timestamp upper bound | |
| tags | No | Filter by tags. Use project name as first tag for scoping. | |
| tag_mode | No | "any" matches memories with any tag (default), "all" requires all tags | |
| tag_match | No | "exact" for exact tag match (default), "prefix" for starts-with matching | |
| 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. | |
| expand_relations | No | Follow graph relationships from seed results to find related memories. | |
| auto_decompose | No | Auto-extract entities and topics from query to generate supplementary searches. | |
| expansion_limit | No | Max total expanded memories (default: 25) | |
| relation_limit | No | Max relations to follow per seed memory (default: 5) | |
| 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. | |
| 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. | |
| context | No | Context label (e.g., "coding-style", "architecture"). Boosts matching preferences. | |
| language | No | Programming language hint (e.g., "python", "typescript"). Prioritizes language-specific memories. | |
| active_path | No | Current file path for language auto-detection (e.g., "src/auth.ts") | |
| context_tags | No | Priority tags to boost in results (e.g., ["coding-style", "preferences"]) | |
| context_types | No | Priority memory types to boost (e.g., ["Style", "Preference"]) | |
| priority_ids | No | Specific memory IDs to ensure are included in results | |
| per_query_limit | No | Per-query result limit when using queries[] (default: 5) | |
| sort | No | Result ordering (use time_* for chronological recaps) | |
| format | No | Output format: text (default), items (per-memory), detailed (with metadata), json (raw) | text |
| offset | No | Result offset for pagination |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | Yes | Number of memories returned | |
| mode | No | Mode that produced the result. | |
| has_more | No | Enumeration mode only: true if more pages exist past `offset + limit`. | |
| limit | No | Enumeration mode only: page size used for this response. | |
| offset | No | Enumeration mode only: offset used for this response. | |
| results | Yes | Array of matching memories with scores | |
| dedup_removed | No | Number of duplicate results removed (when using multiple queries) |