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

# Recall Memories

> Recall and retrieve raw memories by semantic similarity

Search your memories and get raw results without AI response generation. Useful for browsing memories or building custom experiences.

<ParamField body="text" type="string" required>
  Search query. Max 1,000 characters.
</ParamField>

<ParamField body="source" type="string">
  Optional source filter, such as `text`, `email`, `github`, or `google_meets`. The API key must have access to the requested source.
</ParamField>

<RequestExample>
  ```bash curl theme={null}
  curl -X POST https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev/v1/memories/recall \
    -H "x-api-key: $ENGRAMME_API_KEY" \
    -F "text=team meetings"
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev/v1/memories/recall",
      headers={"x-api-key": os.environ["ENGRAMME_API_KEY"]},
      data={"text": "team meetings"}
  )

  for memory in response.json()["memories"]:
      print(f"[{memory['score']:.2f}] {memory['content']['narrative'][:100]}...")
  ```

  ```javascript JavaScript theme={null}
  const apiKey = process.env.ENGRAMME_API_KEY;
  const formData = new FormData();
  formData.append('text', 'team meetings');

  const response = await fetch(
    'https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev/v1/memories/recall',
    {
      method: 'POST',
      headers: { 'x-api-key': apiKey },
      body: formData
    }
  );

  const data = await response.json();
  data.memories.forEach(m => {
    console.log(`[${m.score.toFixed(2)}] ${m.content.narrative}`);
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "trace_id": "9b1c2d3e-4f56-7890-abcd-1234567890ef",
    "memories": [
      {
        "custom_id": "meeting-jan15_memory_0",
        "item_id": "meeting-jan15",
        "score": 0.94,
        "source": "text",
        "content": {
          "narrative": "I attended the weekly team sync with Sarah, Mike, and Jennifer. We reviewed sprint progress and discussed the upcoming product launch timeline.",
          "participants": ["Sarah", "Mike", "Jennifer"],
          "when": "January 15, 2025, 10:00 AM",
          "where": "Conference Room B",
          "other_entities": [
            {"entity_name": "Q1 Roadmap", "entity_type": "Project"}
          ],
          "tags": ["meeting", "team-sync", "sprint"]
        }
      },
      {
        "custom_id": "meeting-jan08_memory_1",
        "item_id": "meeting-jan08",
        "score": 0.87,
        "source": "text",
        "content": {
          "narrative": "I led the Q1 planning session with the engineering team. We prioritized three main objectives for the quarter.",
          "participants": ["Alex", "Mike", "Sarah"],
          "when": "January 8, 2025",
          "where": "Virtual",
          "tags": ["planning", "Q1", "engineering"]
        }
      }
    ],
    "qa": [],
    "chunks": []
  }
  ```

  ```json 400 theme={null}
  {
    "detail": "Query text is required"
  }
  ```
</ResponseExample>

<Note>
  A missing `text` form field may return FastAPI's standard `422` validation response. A blank or whitespace-only `text` value returns `400`.
</Note>

## Response Fields

Recall returns `trace_id`, `memories`, `qa`, and `chunks`. See [Response Fields](/reference/response-fields) for the shared memory result schema.

## Use Cases

<CardGroup cols={2}>
  <Card title="Memory Browser" icon="list">
    Display memories in a list view for users to browse
  </Card>

  <Card title="Debugging" icon="bug">
    See exactly which memories are being retrieved
  </Card>

  <Card title="Custom UI" icon="paintbrush">
    Build custom visualizations with raw memory data
  </Card>

  <Card title="Filtering" icon="filter">
    Post-process results by date, participants, etc.
  </Card>
</CardGroup>

<Note>
  Recall can return an empty list if processing has not finished, no memories match the query, or the API key is scoped away from the relevant source.
</Note>