Is document metadata used in recall and reflect queries?

[gpshenoy]

1. I am ingesting documents along with metadata ( key value pairs ) using the retain API.  However when I query using recall, I noticed that the data is not implicitly filtered by the associated metadata.  Can you please specify how hindsight uses metadata in recall & reflect ?

eg: If I am ingesting documents with metadata like below, Can I get all the memories that have area_path organisation ? Is there a plan to support an API like listMemories that can give me all the memories based on a filter criteria ?

{
    "async": false,
    "items": [
        {
            "content": "Resource assignment for Task 128 scheduled to start Mon Mar 30",
            "context": "Resource assignment for Task 128",
            "timestamp": "2026-08-12T17:00:00Z",
            "document_id": "N-1031",
            "metadata": {
                "event_type": "milestone",
                "source_file": "/path/to/src",
                "source_fidelity": "direct_quote",
                "knowledge_type": "factual",
                "area_path": "organisation",
                "workstream": "PMO",
                "sentiment": "neutral",
                "priority": "high",
                "status": "open",
                "impact": "high",
                "related_document_id": "N-1027"
            }
        }
    ]
}

2. If my metadata has information on how two documents are related, will this info be used to establish link between the corresponding entities ? In the eg. below, will related_document_id be used to establish a link between the memories generated from document 1031 and 1027?

eg:

{
    "async": false,
    "items": [
        {
            "content": "Resource assignment for Task 128 scheduled to start Mon Mar 30",
            "context": "Resource assignment for Task 128",
            "timestamp": "2026-08-12T17:00:00Z",
            "document_id": "N-1031",
            "metadata": {
                "event_type": "milestone",
                "source_file": "/path/to/src",
                "source_fidelity": "direct_quote",
                "knowledge_type": "factual",
                "area_path": "organisation",
                "workstream": "PMO",
                "sentiment": "neutral",
                "priority": "high",
                "status": "open",
                "impact": "high",
                "related_document_id": "N-1027"
            }
        }
    ]
}

[nicoloboschi]

Hi

1. Metadata are not used for filtering, they are only returned along with the memory during recall to give your client application structured context - https://hindsight.vectorize.io/developer/api/retain#metadata
   In order to do "metadata filtering", you must use Tags which provides document filtering and isolation.

2. No, document metadata are purely static data used for convenience and context enrichment during the recall. Links are generated by LLMs which, at the moment, doesn't have visibility on them (which now I'm realizing could be helpful and might be a good improvement)

[gpshenoy]

Thank you @nicoloboschi