Skip to main content
POST
/
api
/
v2
/
agents
/
{agent_id}
/
remember
/
extract
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
  }'

{
  "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
}

​
Overview

Distills a chat-style conversation transcript into typed memory candidates, using the same Moorcheh answer-generation path as the RAG 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.

​
Authentication

API clients do not send an API key or Authorization header.
​
X-Session-Token
string
required
Session token from Activate Agent. Must match agent_id.

​
Path Parameters

​
agent_id
string
required
The unique identifier of the agent.

​
Body

​
messages
array
required
Array of {role, content} conversation message objects. Bounded to 200 messages.
​
dry_run
boolean
When true, returns extracted candidates without storing them. Defaults to false.
​
max_memories
integer
Maximum number of memories to extract. Bounded to 100.
​
ai_model
string
Optional model override for extraction. If omitted, the server default applies.
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
  }'

{
  "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
}

​
Next Steps