--- title: "Recall memory" method: POST path: "/v1/default/banks/{bank_id}/memories/recall" tags: ["Memory"] --- # Recall memory `POST /v1/default/banks/{bank_id}/memories/recall` ## Request - Base URL: `https://hindsight.vectorize.io` (the document declares no server; this is the origin it was published from) - URL: `https://hindsight.vectorize.io/v1/default/banks/{bank_id}/memories/recall` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) Recall memory using semantic similarity and spreading activation. The `types` parameter is optional and may contain any of: - `world`: General knowledge about people, places, events, and things that happen - `experience`: Memories about experience, conversations, actions taken, and tasks performed - `observation`: Consolidated knowledge synthesized from facts If `types` is omitted, all fact types are recalled. ## Path parameters - `bank_id` string, required ## Headers - `authorization` string, nullable ## Request body - RecallRequest: Request model for recall endpoint. - `query` string, required - `types` string[], nullable: List of fact types to recall: 'world', 'experience', 'observation'. Defaults to all fact types if not specified. - `prefer_observations` boolean, nullable: When recalling raw facts ('world'/'experience') together with 'observation', drop any raw fact that an observation in the results was consolidated from, so the observation supersedes it and you don't get duplicate content. The freed slots are backfilled with the next results, keeping the result count at the requested budget. When omitted, uses the bank/global recall_prefer_observations config (false unless configured). No effect unless 'observation' and at least one raw type are both requested. - `rerank` RerankOptions: What the decision-model reranker does beyond ordering. Each field left unset (null) uses the bank/global config; neither has any effect unless a decision model is set up for recall. - `prune` boolean, nullable: Drop the results the decision model judges no help to the query, instead of only ranking them last. Costs no extra request. When omitted, uses the bank/global recall_decision_model_prune config (false unless configured). - `dedup` boolean, nullable: Drop a result that repeats a better-ranked one, so the same fact comes back once. Costs one more decision-model request after the ranking one. When omitted, uses the bank/global recall_decision_model_dedup config (false unless configured). - `budget` 'low' | 'mid' | 'high': Budget levels for recall/reflect operations. - `max_tokens` integer - `trace` boolean - `query_timestamp` string, nullable: ISO format date string (e.g., '2023-05-30T23:40:00'). Used as the query-time anchor for relative temporal expressions and recency scoring. - `include` IncludeOptions: Options for including additional data in recall results. - `entities` EntityIncludeOptions: Options for including entity observations in recall results. - `max_tokens` integer: Maximum tokens for entity observations - `chunks` ChunkIncludeOptions: Options for including chunks in recall results. - `max_tokens` integer: Maximum tokens for chunks (chunks may be truncated) - `source_facts` SourceFactsIncludeOptions: Options for including source facts for observation-type results. - `max_tokens` integer: Maximum total tokens for source facts across all observations (-1 = unlimited) - `max_tokens_per_observation` integer: Maximum tokens of source facts per observation (-1 = unlimited) - `tags` string[], nullable: Filter memories by tags. If not specified, all memories are returned. Omitting tags (or passing []) together with tags_match='exact' filters to untagged/global observations only (the scope written by observation_scopes='shared'). - `tags_match` 'any' | 'all' | 'any_strict' | 'all_strict' | 'exact': How to match tags: 'any' (OR, includes untagged), 'all' (AND, includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged), 'exact' (set-equality on the full scope, excludes untagged). With 'exact' and no tags (or []), the empty global scope is selected and only untagged memories match. - `tag_groups` union[], nullable: Compound tag filter using boolean groups. Groups in the list are AND-ed. Each group is a leaf {tags, match} or compound {and: [...]}, {or: [...]}, {not: ...}. A leaf may set resolve='fuzzy' to match its tags against the bank's tags by trigram similarity instead of literally, so a query that says 'typsecript' still reaches memories tagged 'typescript'. - union - TagGroupLeaf: A leaf tag filter: matches memories by tag list and match mode. - `tags` string[], required - `match` 'any' | 'all' | 'any_strict' | 'all_strict' | 'exact' - `resolve` 'exact' | 'fuzzy' - TagGroupAndInput: Compound AND group: all child filters must match. - `and` union[], required - union - TagGroupLeaf: A leaf tag filter: matches memories by tag list and match mode. - … - TagGroupAndInput (recursive) - TagGroupOrInput: Compound OR group: at least one child filter must match. - … - TagGroupNotInput: Compound NOT group: child filter must NOT match. - … - TagGroupOrInput: Compound OR group: at least one child filter must match. - `or` union[], required - union - TagGroupLeaf: A leaf tag filter: matches memories by tag list and match mode. - … - TagGroupAndInput: Compound AND group: all child filters must match. - … - TagGroupOrInput (recursive) - TagGroupNotInput: Compound NOT group: child filter must NOT match. - … - TagGroupNotInput: Compound NOT group: child filter must NOT match. - `not` union, required - TagGroupLeaf: A leaf tag filter: matches memories by tag list and match mode. - `tags` string[], required - `match` 'any' | 'all' | 'any_strict' | 'all_strict' | 'exact' - `resolve` 'exact' | 'fuzzy' - TagGroupAndInput: Compound AND group: all child filters must match. - `and` union[], required - … - TagGroupOrInput: Compound OR group: at least one child filter must match. - `or` union[], required - … - TagGroupNotInput (recursive) - `min_scores` MinScores: Optional per-stage score floors for recall. Every floor is inclusive (``>=``). The four floors act at two different levels, and the distinction decides what a returned result is guaranteed to satisfy. ``semantic`` and ``keyword`` are **retrieval-level** cutoffs pushed into their own SQL arm (overriding the global ``semantic_min_similarity`` / ``bm25_min_score`` config for this request), so they prune weak matches before fusion. Each one constrains **only the arm it names**. Recall fuses four arms — semantic, keyword, graph and temporal — and a result reaches the response if *any* arm surfaced it, so a returned result may legitimately carry ``null`` for a stage it was not surfaced by, and results reached through the graph or temporal arm carry neither ``semantic`` nor ``keyword``. A *non-null* score always clears its floor — the gap is only ever a ``null``. Setting both does **not** restrict the response to results that clear both: they are not a predicate over each fused result. This is deliberate — an intersection would discard the strong single-arm matches that hybrid retrieval exists to find (a paraphrase with no lexical overlap, an exact identifier the embedding scores poorly). ``reranker`` and ``final`` are **post-query** filters applied to every scored result after fusion and reranking, so these *are* per-result predicates: a returned result always clears them. Use them, not the retrieval floors, to make recall abstain on low-confidence queries. Any field left None imposes no floor; all-None (the default) means no score filtering. - `semantic` number, nullable: Retrieval-level, semantic arm only: minimum vector similarity (0-1). A result the semantic arm did not surface reports `semantic: null` and is unaffected by this floor. - `keyword` number, nullable: Retrieval-level, keyword arm only: minimum keyword/full-text (BM25) score. A result the keyword arm did not surface reports `keyword: null` and is unaffected by this floor. - `reranker` number, nullable: Post-query: minimum normalized reranker score (0-1). Applied to every returned result. Rejected with HTTP 400 when the reranker scores by rank position (a decision model, or TypeSafe), since a floor would only keep a fixed share of the results. - `final` number, nullable: Post-query: minimum final ranking score. Applied to every returned result. - `temporal_window` TemporalWindow: A caller-supplied window for recall's temporal arm. Supplying this **replaces the date extraction** recall would otherwise run over the query text, so a caller that already knows the range it means does not have to phrase it in English and hope the parser agrees. It is **not a filter**. The temporal arm is one of four retrieval arms: it surfaces memories whose own dates (``mentioned_at`` / ``occurred_start`` / ``occurred_end``) fall inside the window so fusion can rank them higher. The semantic, keyword and graph arms are unaffected, so results dated outside the window are still returned. Narrowing results to a date range is a different operation this does not provide. Has no effect when the bank's ``enable_temporal_retrieval`` config is off: that flag gates the arm itself, and stays the single switch for it. - `start` string, date-time, required: Start of the window (inclusive). - `end` string, date-time, required: End of the window (inclusive). ## Response `200` Successful Response - RecallResponse: Response model for recall endpoints. - `results` RecallResult[], required - `id` string, required - `text` string, required - `type` string, nullable - `entities` string[], nullable - `context` string, nullable - `occurred_start` string, nullable - `occurred_end` string, nullable - `mentioned_at` string, nullable - `document_id` string, nullable - `metadata` object, nullable - `chunk_id` string, nullable - `tags` string[], nullable - `source_fact_ids` string[], nullable - `scores` RecallScores: Per-result recall scores from different stages of the pipeline. ``final`` is the value results are ranked by. The others are diagnostic and can be filtered on via the recall ``min_scores`` request parameter. ``semantic`` and ``keyword`` are the raw per-strategy retrieval scores (``None`` when that strategy did not surface this result); ``reranker`` is the cross-encoder's normalized relevance. - `final` number, required: Final ranking score (combined reranker + recency/temporal/proof boosts) - `reranker` number, nullable: Cross-encoder relevance, normalized 0-1. None when the reranker is a passthrough (rrf/interleave modes). - `semantic` number, nullable: Vector cosine similarity (0-1). None if this result was not surfaced semantically. - `keyword` number, nullable: Keyword/full-text (BM25) score (>= 0, unbounded). None if this result was not surfaced by keyword search. - `attachments` ChunkAttachment[], nullable: Attachments this fact was drawn from, as recorded per fact at extraction time — the same edge the memory read endpoints return, not everything its chunk happened to carry. A fact stated in prose reports none; an observation reports those of the facts it was consolidated from. Omitted when there are none. - `id` string, required: The id inside the text's placeholder; a prefix of the bytes' sha256. - `hash` string, required: Full sha256 of the attachment bytes. - `kind` string, required: 'image' or 'file', as the caller sent it. - `media_type` string, required: MIME type of the attachment. - `byte_size` integer, required: Size of the attachment in bytes. - `filename` string, nullable: Original filename, when the caller supplied one. - `url` string, required: Bank-scoped API path serving the bytes. Requires the same authorization as the bank. - `trace` object, nullable - `entities` object, nullable: Entity states for entities mentioned in results - `chunks` object, nullable: Chunks for facts, keyed by chunk_id - `source_facts` object, nullable: Source facts for observation-type results, keyed by fact ID - `source_facts_truncated` boolean, nullable: Whether the source_facts map was cut short by the token budget. When true, some IDs in results[].source_fact_ids have no entry in source_facts — the budget ran out, the references are not dangling. Only set when source facts were requested. ## Other responses - `422`: Validation Error ## Changes - **2026-11-07** `45e711cd0897`: 3 info - added the new optional request property `rerank` - the `prefer_observations` request property default value `false` was removed - request property `prefer_observations` list-of-types was widened by adding types `null` to media type `application/json` - **2026-10-04** `4fda98b75f63`: 1 warning, 26 info - removed the optional property `detail/items/url` from the response with the `422` status - added the new optional request property `min_scores` - added the new optional request property `prefer_observations` - added the new optional request property `tag_groups/anyOf[subschema #1]/items/anyOf[subschema #1: TagGroupLeaf]/resolve` - …23 more - **2026-05-15** `0d08f271b9db`: 1 breaking, 4 info - removed `#/components/schemas/TagGroupAnd, #/components/schemas/TagGroupOr, #/components/schemas/TagGroupNot` from the `tag_groups/anyOf[subschema #1]/items/` request property `anyOf` list - added `#/components/schemas/TagGroupAnd-Input, #/components/schemas/TagGroupOr-Input, #/components/schemas/TagGroupNot-Input` to the `tag_groups/anyOf[subschema #1]/items/` request property `anyOf` list - added the optional property `detail/items/ctx` to the response with the `422` status - added the optional property `detail/items/input` to the response with the `422` status - …1 more [Operation history](https://skmtc.dev/vectorize/apis/hindsight-http-api/changes/v1/default/banks/:bank_id/memories/recall/post.md) --- [API](https://skmtc.dev/vectorize/apis/hindsight-http-api.md) - [All operations](https://skmtc.dev/vectorize/apis/hindsight-http-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vectorize/apis/hindsight-http-api/revisions/951fd4ce91d1?raw)