recall
Search memories by text or entity name. Results are re-ranked by relevance, heat, and importance, with explanations. Use at task start to recall prior work.
Instructions
Retrieve memories relevant to the current context using full-text search (BM25) + entity-name match, re-ranked by a composite score (relevance × heat × momentum × importance). Returns only what fits in the token budget, with match_reasons explaining WHY each memory was returned. Opportunistically refreshes stale momentum scores for entities in the result set. Supports pagination via offset/has_more. Layer aliases accepted. Use at the start of any task that might involve prior work.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | What you want to remember (free-text, entity name, or FTS5 MATCH expression) | |
| entity_name | No | Optional — narrow to a specific entity | |
| layer | No | Optional layer filter. Accepts aliases (decisions/warnings/how/etc.) as well as canonical names. | |
| band | No | Optional — only return memories whose heat_band matches. | |
| max_tokens | No | Approx token budget. Default 2000. Either max_tokens or limit stops iteration (whichever fires first). | |
| limit | No | Optional hard cap on number of memories. Stops at min(max_tokens-budget, limit). | |
| offset | No | Skip this many top results (pagination). Use has_more from prior response to decide next offset. | |
| mark_accessed | No | Set false for preview / listing queries that should not bump heat. |