---
id: recall-memories
title: "Recall memory"
description: "Recall memory using semantic similarity and spreading activation."
sidebar_label: "Recall memory"
hide_title: true
hide_table_of_contents: true
api: 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
sidebar_class_name: "post api-method"
info_path: docs/api-reference/endpoints/hindsight-http-api
custom_edit_url: null
---

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Recall memory"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v1/default/banks/{bank_id}/memories/recall"}
  context={"endpoint"}
>
  
</MethodEndpoint>



Recall memory using semantic similarity and spreading activation.

    The type parameter is optional and must be one of:
    - 'world': General knowledge about people, places, events, and things that happen
    - 'experience': Memories about experience, conversations, actions taken, and tasks performed
    - 'opinion': The bank's formed beliefs, perspectives, and viewpoints

    Set include_entities=true to get entity observations alongside recall results.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"bank_id","in":"path","required":true,"schema":{"type":"string","title":"Bank Id"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"type":"string","title":"Query"},"types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Types","description":"List of fact types to recall (defaults to all if not specified)"},"budget":{"default":"mid","type":"string","enum":["low","mid","high"],"title":"Budget","description":"Budget levels for recall/reflect operations."},"max_tokens":{"type":"integer","title":"Max Tokens","default":4096},"trace":{"type":"boolean","title":"Trace","default":false},"query_timestamp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query Timestamp","description":"ISO format date string (e.g., '2023-05-30T23:40:00')"},"filters":{"anyOf":[{"items":{"properties":{"key":{"type":"string","title":"Key","description":"Metadata key to filter on"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value","description":"Value to match. If None with match_unset=True, matches any record where key is not set."},"match_unset":{"type":"boolean","title":"Match Unset","description":"If True, also match records where this metadata key is not set","default":true}},"type":"object","required":["key"],"title":"MetadataFilter","description":"Filter for metadata fields. Matches records where (key=value) OR (key not set) when match_unset=True.","example":{"key":"source","match_unset":true,"value":"slack"}},"type":"array"},{"type":"null"}],"title":"Filters","description":"Filter by metadata. Multiple filters are ANDed together."},"include":{"description":"Options for including additional data (entities are included by default)","properties":{"entities":{"anyOf":[{"properties":{"max_tokens":{"type":"integer","title":"Max Tokens","description":"Maximum tokens for entity observations","default":500}},"type":"object","title":"EntityIncludeOptions","description":"Options for including entity observations in recall results."},{"type":"null"}],"description":"Include entity observations. Set to null to disable entity inclusion.","default":{"max_tokens":500}},"chunks":{"anyOf":[{"properties":{"max_tokens":{"type":"integer","title":"Max Tokens","description":"Maximum tokens for chunks (chunks may be truncated)","default":8192}},"type":"object","title":"ChunkIncludeOptions","description":"Options for including chunks in recall results."},{"type":"null"}],"description":"Include raw chunks. Set to {} to enable, null to disable (default: disabled)."}},"type":"object","title":"IncludeOptions"}},"type":"object","required":["query"],"title":"RecallRequest","description":"Request model for recall endpoint.","example":{"budget":"mid","filters":[{"key":"source","match_unset":true,"value":"slack"}],"include":{"entities":{"max_tokens":500}},"max_tokens":4096,"query":"What did Alice say about machine learning?","query_timestamp":"2023-05-30T23:40:00","trace":true,"types":["world","experience"]}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"results":{"items":{"properties":{"id":{"type":"string","title":"Id"},"text":{"type":"string","title":"Text"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"entities":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Entities"},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Context"},"occurred_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Occurred Start"},"occurred_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Occurred End"},"mentioned_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mentioned At"},"document_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Id"},"metadata":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Metadata"},"chunk_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chunk Id"}},"type":"object","required":["id","text"],"title":"RecallResult","description":"Single recall result item.","example":{"chunk_id":"456e7890-e12b-34d5-a678-901234567890","context":"work info","document_id":"session_abc123","entities":["Alice","Google"],"id":"123e4567-e89b-12d3-a456-426614174000","mentioned_at":"2024-01-15T10:30:00Z","metadata":{"source":"slack"},"occurred_end":"2024-01-15T10:30:00Z","occurred_start":"2024-01-15T10:30:00Z","text":"Alice works at Google on the AI team","type":"world"}},"type":"array","title":"Results"},"trace":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Trace"},"entities":{"anyOf":[{"additionalProperties":{"properties":{"entity_id":{"type":"string","title":"Entity Id"},"canonical_name":{"type":"string","title":"Canonical Name"},"observations":{"items":{"properties":{"text":{"type":"string","title":"Text"},"mentioned_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mentioned At"}},"type":"object","required":["text"],"title":"EntityObservationResponse","description":"An observation about an entity."},"type":"array","title":"Observations"}},"type":"object","required":["entity_id","canonical_name","observations"],"title":"EntityStateResponse","description":"Current mental model of an entity."},"type":"object"},{"type":"null"}],"title":"Entities","description":"Entity states for entities mentioned in results"},"chunks":{"anyOf":[{"additionalProperties":{"properties":{"id":{"type":"string","title":"Id"},"text":{"type":"string","title":"Text"},"chunk_index":{"type":"integer","title":"Chunk Index"},"truncated":{"type":"boolean","title":"Truncated","description":"Whether the chunk text was truncated due to token limits","default":false}},"type":"object","required":["id","text","chunk_index"],"title":"ChunkData","description":"Chunk data for a single chunk."},"type":"object"},{"type":"null"}],"title":"Chunks","description":"Chunks for facts, keyed by chunk_id"}},"type":"object","required":["results"],"title":"RecallResponse","description":"Response model for recall endpoints.","example":{"chunks":{"456e7890-e12b-34d5-a678-901234567890":{"chunk_index":0,"id":"456e7890-e12b-34d5-a678-901234567890","text":"Alice works at Google on the AI team. She's been there for 3 years..."}},"entities":{"Alice":{"canonical_name":"Alice","entity_id":"123e4567-e89b-12d3-a456-426614174001","observations":[{"mentioned_at":"2024-01-15T10:30:00Z","text":"Alice works at Google on the AI team"}]}},"results":[{"chunk_id":"456e7890-e12b-34d5-a678-901234567890","context":"work info","entities":["Alice","Google"],"id":"123e4567-e89b-12d3-a456-426614174000","occurred_end":"2024-01-15T10:30:00Z","occurred_start":"2024-01-15T10:30:00Z","text":"Alice works at Google on the AI team","type":"world"}],"trace":{"num_results":1,"query":"What did Alice say about machine learning?","time_seconds":0.123}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>