Skip to main content
POST
/
api
/
Memory
/
recall
Search memories using semantic similarity
curl --request POST \
  --url https://app.recallio.ai/api/Memory/recall \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "userId": "user_123",
  "projectId": "project_abc",
  "query": "What are the user's UI preferences?",
  "scope": "user",
  "tags": [
    "preferences",
    "ui"
  ]
}
EOF
[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "userId": "user_123",
    "projectId": "project_abc",
    "content": "The user prefers dark mode and wants notifications disabled on weekends",
    "tags": [
      "preferences",
      "ui",
      "notifications"
    ],
    "metadata": {
      "timestamp": "2025-08-02T14:30:00Z",
      "category": "user-preferences",
      "source": "settings-page"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "expiresAt": "2024-12-31T23:59:59Z",
    "categories": [
      "preferences",
      "ui",
      "notifications"
    ],
    "similarityScore": 0.85,
    "similarityLevel": "Very Good"
  }
]

Authorizations

​
Authorization
string
header
required

JWT Authorization header using the Bearer scheme. Example: "Authorization: Bearer {token}"

Query Parameters

​
summarized
boolean
default:false

If the return facts should be summarized (because of the delay, this is usually better to use 'recall-summary' endpoint if you expect a summary

​
reRank
boolean
default:false

If the individual fact returns should be reranked via LLM. This is only usefull when the amount of valid return fact is larger than the limit

​
type
string
default:facts

To retrieve 'facts' (default) or 'raw' memories. Facts will return a better result

​
similarityThreshold
number<double>
default:0.3

To control the similiraty treshold in the consine research. 0.3 (default) allows a wider search, 0.7 would filter more. Range is between 0 (no similarity) and 1 (extremely similar)

​
limit
integer<int32>
default:10

Amount of facts to retrieve

Body

Search parameters including query, filters, and result limits

​
userId
string
required

User identifier to search memories for

Minimum string length: 1
Example:

"user_123"

​
projectId
string
required

Project identifier to search memories within

Minimum string length: 1
Example:

"project_abc"

​
query
string
required

Natural language query to search for similar memories. To retrieve all topics, use the '*' wildcard.

Minimum string length: 1
Example:

"What are the user's UI preferences?"

​
scope
string
required

Search scope: 'user' (user-specific), 'project' (project-wide), or 'team' (team-wide)

Minimum string length: 1
Example:

"user"

​
tags
string[] | null

Optional tags to filter memories by

Example:
["preferences", "ui"]

Response

OK

​
id
string<uuid>

Unique identifier for the memory

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
userId
string | null

Identifier of the user who owns this memory

Example:

"user_123"

​
projectId
string | null

Project identifier this memory belongs to

Example:

"project_abc"

​
content
string | null

The stored content/text of the memory

Example:

"The user prefers dark mode and wants notifications disabled on weekends"

​
tags
string[] | null

Tags associated with this memory for categorization

Example:
["preferences", "ui", "notifications"]
​
metadata
any | null

Metadata associated with this memory

Example:
{
  "timestamp": "2025-08-02T14:30:00Z",
  "category": "user-preferences",
  "source": "settings-page"
}
​
createdAt
string<date-time> | null

Timestamp when the memory was created

Example:

"2024-01-15T10:30:00Z"

​
expiresAt
string<date-time> | null

Optional expiration timestamp for the memory

Example:

"2024-12-31T23:59:59Z"

​
categories
string[] | null

Categories associated with this memory

Example:
["preferences", "ui", "notifications"]
​
similarityScore
number<double>

Cosine similarity score between the query and this memory (0.0 to 1.0). Higher values indicate better matches

Example:

0.85

​
similarityLevel
string | null

Human-readable interpretation of the similarity score (Excellent, Very Good, Good, Fair, Moderate, Low)

Example:

"Very Good"