Skip to main content
POST
/
api
/
v2
/
agents
/
{agent_id}
/
recall
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/recall" \
  -H "X-Session-Token: your_session_token" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "user preferences",
    "limit": 10,
    "min_similarity": 0.2,
    "type": ["preference"]
  }'

{
  "agent_id": "my-agent",
  "session_id": "sess_cf824a95d305",
  "query": "user preferences",
  "memories": [
    {
      "id": "3e681f12-a28c-4d1d-9632-b8dadf1f9d0c",
      "title": "User Preference Note",
      "content": "Prefers email communication",
      "text": "[PREFERENCE] User Preference Note\n\nPrefers email communication",
      "type": "preference",
      "confidence": 0.98,
      "status": "active",
      "tags": [],
      "created_at": "2026-03-26T09:00:00.000000",
      "updated_at": "2026-03-26T09:00:00.000000",
      "actor_id": "my-agent",
      "source": "agent",
      "scope_type": "agent",
      "scope_id": "my-agent",
      "score": 0.086334,
      "provenance": "explicit_statement",
      "validation_count": 0,
      "contradiction_detected": false
    }
  ],
  "count": 1
}

​
Overview

Run semantic search across stored memories. This retrieves contextually relevant memories for the active agent based on semantic similarity to the query. Filters are sent as JSON in the request body only (no query-string parameters).

​
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.
​
Content-Type
string
required
Must be application/json

​
Path Parameters

​
agent_id
string
required
The unique identifier of the agent.

​
Body

​
query
string
required
Natural-language search text matched against the agent’s memories (max 1000 characters).
​
limit
integer
Maximum number of results to return. Range 1–100. If omitted, the server default applies (RECALL_LIMIT).
​
min_similarity
number
Minimum similarity score in the range 0.0–1.0 to filter out less relevant memories.
​
type
array
Optional list of memory type filters (e.g. ["fact", "preference"]).

​
ITS Scoring System

Memories are scored using Information Theoretic Similarity (ITS), providing nuanced relevance measurements. Use the min_similarity parameter to filter out results below a certain threshold:
LabelScore RangeDescription
Close Matchscore ≥ 0.894Near-perfect relevance to the query
Very High Relevance0.632 ≤ score < 0.894Strongly related content
High Relevance0.447 ≤ score < 0.632Significantly related content
Good Relevance0.316 ≤ score < 0.447Moderately related content
Low Relevance0.224 ≤ score < 0.316Minimally related content
Very Low Relevance0.1 ≤ score < 0.224Barely related content
Irrelevantscore < 0.1No meaningful relation to the query
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/recall" \
  -H "X-Session-Token: your_session_token" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "user preferences",
    "limit": 10,
    "min_similarity": 0.2,
    "type": ["preference"]
  }'

{
  "agent_id": "my-agent",
  "session_id": "sess_cf824a95d305",
  "query": "user preferences",
  "memories": [
    {
      "id": "3e681f12-a28c-4d1d-9632-b8dadf1f9d0c",
      "title": "User Preference Note",
      "content": "Prefers email communication",
      "text": "[PREFERENCE] User Preference Note\n\nPrefers email communication",
      "type": "preference",
      "confidence": 0.98,
      "status": "active",
      "tags": [],
      "created_at": "2026-03-26T09:00:00.000000",
      "updated_at": "2026-03-26T09:00:00.000000",
      "actor_id": "my-agent",
      "source": "agent",
      "scope_type": "agent",
      "scope_id": "my-agent",
      "score": 0.086334,
      "provenance": "explicit_statement",
      "validation_count": 0,
      "contradiction_detected": false
    }
  ],
  "count": 1
}

​
Next Steps