---
title: "Retrieve memory context for a message"
description: "Retrieve the full memory context that would be injected during a chat turn.\n\nRuns the same pipeline as POST /v1/chat/completions — session context via\ncache/fallback, low-information gating, and per-message graph search.\nReturns raw data, rendered prompts, and cache diagnostics."
---

> Documentation Index
> Fetch the complete documentation index at: https://truememory-docs.mvstg.com/llms.txt
> Use this file to discover all available pages before exploring further.

Path: AI Gateway API › Memory

`POST /memories/retrieve`

Retrieve the full memory context that would be injected during a chat turn.

Runs the same pipeline as POST /v1/chat/completions — session context via
cache/fallback, low-information gating, and per-message graph search.
Returns raw data, rendered prompts, and cache diagnostics.

## Authentication

- `HTTPBearer`, http, header `Authorization`

## Header parameters

- `X-On-Behalf-Of` (`retrieve_memory.header.X-On-Behalf-Of`; any of, optional)
  - any of: `string`, `null`
- `X-External-User-Id` (`retrieve_memory.header.X-External-User-Id`; any of, optional)
  - any of: `string`, `null`
- `X-App-Id` (`retrieve_memory.header.X-App-Id`; any of, optional)
  - any of: `string`, `null`

## Request body

_Required._

- `query` (`retrieve_memory.query`; string, required) — The user message to retrieve memories for
  - minLength 1; maxLength 5000
- `agent_id` (`retrieve_memory.agent_id`; string, required)
- `display_name` (`retrieve_memory.display_name`; any of, optional) — User display name rendered into the context prompt (chat parity)
  - any of: `string`, `null`
- `email` (`retrieve_memory.email`; any of, optional) — User email rendered into the context prompt (chat parity)
  - any of: `string`, `null`
- `graph_ids` (`retrieve_memory.graph_ids`; any of, optional) — Shared knowledge graphs to blend into the per-message retrieval alongside the user's own memory.
  - any of: `array<string>`, `null`

## Example request

```json
{
  "query": "string",
  "agent_id": "string",
  "display_name": "string",
  "email": "string",
  "graph_ids": [
    "string"
  ]
}
```

## Code samples

### cURL

```bash
curl --request POST \
  --url https://truememory-api.mvstg.com/memories/retrieve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "string",
  "agent_id": "string",
  "display_name": "string",
  "email": "string",
  "graph_ids": [
    "string"
  ]
}
'
```

### TypeScript

```typescript
const url = 'https://truememory-api.mvstg.com/memories/retrieve';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Bearer <token>'},
  body: JSON.stringify({
    query: 'string',
    agent_id: 'string',
    display_name: 'string',
    email: 'string',
    graph_ids: ['string']
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://truememory-api.mvstg.com/memories/retrieve"

payload = {
    "query": "string",
    "agent_id": "string",
    "display_name": "string",
    "email": "string",
    "graph_ids": ["string"]
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

## Responses

### 200

Successful Response

#### Example

```json
{
  "query": "string",
  "user_id": "string",
  "agent_id": "string",
  "elapsed_seconds": 0,
  "prompt": "string",
  "context": {
    "data": {
      "entities": [
        {
          "name": "string",
          "summary": "string"
        }
      ],
      "facts": [
        "string"
      ]
    },
    "prompt": "string",
    "elapsed_seconds": 0,
    "cache_hit": true,
    "cache_age_seconds": 0,
    "source": "string",
    "prefetch_in_flight": true,
    "cache_size": 0
  },
  "retrieval": {
    "low_info_skipped": true,
    "results": [
      {
        "id": "string",
        "name": "string",
        "content": "string",
        "created_at": "string",
        "valid_at": "string",
        "source_name": "string",
        "target_name": "string",
        "source_descriptions": [
          "string"
        ],
        "scope": "user",
        "graph_id": "string"
      }
    ],
    "prompt": "string",
    "error": "string",
    "elapsed_seconds": 0,
    "result_count": 0
  }
}
```

- `query` (`retrieve_memory.response.200.query`; string, required)
- `user_id` (`retrieve_memory.response.200.user_id`; string, required)
- `agent_id` (`retrieve_memory.response.200.agent_id`; string, required)
- `elapsed_seconds` (`retrieve_memory.response.200.elapsed_seconds`; number, required)
- `prompt` (`retrieve_memory.response.200.prompt`; any of, required)
  - any of: `string`, `null`
- `context` (`retrieve_memory.response.200.context`; object, required)
  - `data` (`retrieve_memory.response.200.context.data`; object, required)
    - `entities` (`retrieve_memory.response.200.context.data.entities`; array<object>, required)
      - `name` (`retrieve_memory.response.200.context.data.entities.name`; string, required)
      - `summary` (`retrieve_memory.response.200.context.data.entities.summary`; any of, required)
        - any of: `string`, `null`
    - `facts` (`retrieve_memory.response.200.context.data.facts`; array<string>, required)
  - `prompt` (`retrieve_memory.response.200.context.prompt`; any of, required)
    - any of: `string`, `null`
  - `elapsed_seconds` (`retrieve_memory.response.200.context.elapsed_seconds`; number, required)
  - `cache_hit` (`retrieve_memory.response.200.context.cache_hit`; boolean, required)
  - `cache_age_seconds` (`retrieve_memory.response.200.context.cache_age_seconds`; any of, required)
    - any of: `number`, `null`
  - `source` (`retrieve_memory.response.200.context.source`; string, required) — Where the context came from, e.g. cypher_fallback.
  - `prefetch_in_flight` (`retrieve_memory.response.200.context.prefetch_in_flight`; boolean, required)
  - `cache_size` (`retrieve_memory.response.200.context.cache_size`; integer, required)
- `retrieval` (`retrieve_memory.response.200.retrieval`; object, required)
  - `low_info_skipped` (`retrieve_memory.response.200.retrieval.low_info_skipped`; boolean, required)
  - `results` (`retrieve_memory.response.200.retrieval.results`; array<object>, required)
    - `id` (`retrieve_memory.response.200.retrieval.results.id`; string, required)
    - `name` (`retrieve_memory.response.200.retrieval.results.name`; string, required)
    - `content` (`retrieve_memory.response.200.retrieval.results.content`; string, required)
    - `created_at` (`retrieve_memory.response.200.retrieval.results.created_at`; any of, required)
      - any of: `string`, `null`
    - `valid_at` (`retrieve_memory.response.200.retrieval.results.valid_at`; any of, required)
      - any of: `string`, `null`
    - `source_name` (`retrieve_memory.response.200.retrieval.results.source_name`; any of, required)
      - any of: `string`, `null`
    - `target_name` (`retrieve_memory.response.200.retrieval.results.target_name`; any of, required)
      - any of: `string`, `null`
    - `source_descriptions` (`retrieve_memory.response.200.retrieval.results.source_descriptions`; array<string>, required)
    - `scope` (`retrieve_memory.response.200.retrieval.results.scope`; string, required)
      - one of `"user"`, `"graph"`
    - `graph_id` (`retrieve_memory.response.200.retrieval.results.graph_id`; any of, required)
      - any of: `string`, `null`
  - `prompt` (`retrieve_memory.response.200.retrieval.prompt`; any of, required)
    - any of: `string`, `null`
  - `error` (`retrieve_memory.response.200.retrieval.error`; any of, required)
    - any of: `string`, `null`
  - `elapsed_seconds` (`retrieve_memory.response.200.retrieval.elapsed_seconds`; number, required)
  - `result_count` (`retrieve_memory.response.200.retrieval.result_count`; integer, required)

### 422

Validation Error

#### Example

```json
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
```

- `detail` (`retrieve_memory.response.422.detail`; array<object>, optional)
  - `loc` (`retrieve_memory.response.422.detail.loc`; array<any of>, required)
    - any of: `string`, `integer`
  - `msg` (`retrieve_memory.response.422.detail.msg`; string, required)
  - `type` (`retrieve_memory.response.422.detail.type`; string, required)
  - `input` (`retrieve_memory.response.422.detail.input`; unknown, optional)
  - `ctx` (`retrieve_memory.response.422.detail.ctx`; object, optional)


Source: https://truememory-docs.mvstg.com/api/memories/retrieve/index.md