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

# Extract Memories

> Extract typed memory candidates from chat-style conversation turns.

## Overview

Distills a chat-style conversation transcript into typed memory candidates, using the same Moorcheh answer-generation path as the RAG [Answer](/api-reference/ai/generate-ai-answer) endpoint. Candidates are auto-classified into valid memory types, de-duplicated, confidence-scored, and tagged `conversation-extract`. Secrets, API keys, and tokens are explicitly excluded by the extraction prompt.

When `dry_run` is `true`, candidates are returned without writing. Otherwise the candidates are persisted through the same batch memory path used by [Batch Remember](/api-reference/data/batch-remember).

## Authentication

API clients do not send an API key or `Authorization` header.

<ParamField header="X-Session-Token" type="string" required>
  Session token from [Activate Agent](/api-reference/sessions/activate-agent). Must match `agent_id`.
</ParamField>

## Path Parameters

<ParamField path="agent_id" type="string" required>
  The unique identifier of the agent.
</ParamField>

## Body

<ParamField body="messages" type="array" required>
  Array of `{role, content}` conversation message objects. Bounded to 200 messages.
</ParamField>

<ParamField body="dry_run" type="boolean">
  When `true`, returns extracted candidates without storing them. Defaults to `false`.
</ParamField>

<ParamField body="max_memories" type="integer">
  Maximum number of memories to extract. Bounded to 100.
</ParamField>

<ParamField body="ai_model" type="string">
  Optional model override for extraction. If omitted, the server default applies.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "http://localhost:8000/api/v2/agents/my-agent/remember/extract" \
    -H "X-Session-Token: your_session_token" \
    -H "Content-Type: application/json" \
    -d '{
      "messages": [
        {"role": "user", "content": "I prefer email over phone calls"},
        {"role": "assistant", "content": "Got it, I will note that preference."}
      ],
      "dry_run": false,
      "max_memories": 20
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - OK (dry_run: true) theme={null}
  {
    "agent_id": "my-agent",
    "session_id": "sess_abc123",
    "dry_run": true,
    "candidates": [
      {
        "type": "preference",
        "title": "Prefers email communication",
        "content": "User prefers email over phone calls",
        "confidence": 0.9,
        "source": "conversation",
        "provenance": "explicit_statement"
      }
    ],
    "count": 1
  }
  ```

  ```json 200 - OK (dry_run: false) theme={null}
  {
    "agent_id": "my-agent",
    "session_id": "sess_abc123",
    "dry_run": false,
    "candidates": [
      {
        "type": "preference",
        "title": "Prefers email communication",
        "content": "User prefers email over phone calls",
        "confidence": 0.9,
        "source": "conversation",
        "provenance": "explicit_statement"
      }
    ],
    "total_submitted": 1,
    "successful": 1,
    "failed": 0,
    "results": [
      {
        "id": "3e681f12-a28c-4d1d-9632-b8dadf1f9d0c",
        "status": "stored"
      }
    ]
  }
  ```

  ```json 401 - Unauthorized (Missing Token) theme={null}
  {
    "detail": "Missing session token. Use X-Session-Token header."
  }
  ```
</ResponseExample>

## Next Steps

* [Remember](/api-reference/data/remember) to store a single memory directly
* [Batch Remember](/api-reference/data/batch-remember) to store a pre-built list of memories
* [Recall](/api-reference/search/recall) to search stored memories