recall
Retrieve past memories by semantic similarity to answer queries about decisions, preferences, or people; refine results when initial confidence is low.
Instructions
Search memories by semantic similarity, or refine low-confidence results.
MODES:
Search (default): recall("project architecture decisions")
Refine: recall("PostgreSQL vs MySQL decision", refine_from="database choice", refine_exclude=["rid1"]) (Relevance feedback moved to memory(action="feedback") in v0.10 — recall is now purely read-only.)
WHEN TO USE: conversation start (summarize the user's first message); when the user references past decisions, people, preferences, or "last time"; when unsure about something the user assumes you know. Refine when first confidence < 0.5. After USING a recalled memory, reinforce it via memory(action="feedback", rid=..., feedback="relevant"). For "what is the CURRENT/latest X", prefer memory(action="chain_head") — similarity favors the most-similar revision, not the newest. For "what happened , in what order" ("tonight", "this week") use temporal(action="range") or since/until here — those words name the time frame, not the content; bare similarity cannot see the window.
QUERY: one short natural-language sentence (5-10 words), NOT a keyword list — keyword stuffing degrades quality. One focused question per call; separate calls for separate topics.
TRUST SIGNALS: each hit's why_retrieved may carry staleness warnings
("aged", "rarely confirmed", "superseded by a newer record"). Treat
flagged hits as weak evidence — prefer fresher results or chain_head,
and note the flag if you act on one anyway.
Args: query: Short natural language sentence (5-10 words). NOT a keyword list. top_k: Max results (default 10). 3-5 for focused, 10-20 for broad. memory_type: Filter: "semantic", "episodic", "procedural". domain: Filter: "work", "preference", "architecture", "people", etc. source: Filter: "user", "inference", "document", "system". namespace: Filter by namespace. include_consolidated: Include merged memories. include_superseded: v0.10 — recall EXCLUDES superseded records by default (current-by-default). Set True only for history / archaeology over a revision chain. expand_entities: Use knowledge graph boosting (default True). min_score_ratio: Drop hits scoring below this fraction of the TOP hit (0.8 = keep only near-as-good matches). Semantic search always returns top_k, even when one result is relevant and the rest are noise; this trims the tail instead of making you judge it. since: Only memories from this instant on — "2026-08-01", "2026-08-01T14:30:00Z", "6h"/"7d" (ago), or unix seconds. Filters BEFORE ranking: top_k is chosen inside the window. until: Window end (same formats; default now). Alone = up to then. refine_from: Original query text to refine from. query becomes the refinement. refine_exclude: Memory IDs to exclude when refining.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| since | No | ||
| top_k | No | ||
| until | No | ||
| domain | No | ||
| source | No | ||
| namespace | No | ||
| memory_type | No | ||
| refine_from | No | ||
| refine_exclude | No | ||
| expand_entities | No | ||
| min_score_ratio | No | ||
| include_superseded | No | ||
| include_consolidated | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |