Guides

Retrieval

Two endpoints read memory. They share a request shape and differ in how much work happens between your question and the answer.

Which one to use

Endpoint	Pipeline	Use when
/memory/recall	Decompose the query, search, rerank, then LLM-select the answering facts	The question needs reasoning over phrasing, time, or several facts combined
/memory/search	Vector similarity on the raw query. No LLM at all	Fastest and cheapest. Direct semantic matching is enough

Recall is the one that returns a small, precise set. Search returns candidates and leaves the filtering to you.

Shared parameters

Both accept the same body.

Field	Required	Description
query	Yes	The natural-language question or search phrase.
thread_id	No	Restrict to one thread. Omit to read only facts attached to no thread. To read everything, send `scope: "agent"`.
task_id	No	Also read the shared task pool for that id.
event_date	No	The "as of" date. Anchors relative phrases in the query and filters historical facts. Defaults to now.
include_sources	No	`true` also returns the original text behind the returned facts. Default `false`. See Including sources.
scope	No	`thread` (default) reads the given thread plus thread-less facts. `agent` reads every thread for the agent and ignores `thread_id`.
source_kind	No	Only use facts extracted from sources of this kind, e.g. `DOCUMENT`.
author	No	Only use facts from sources with this `author`. Matched case-insensitively.
path	No	Only use facts from the source with this `path`, e.g. one uploaded file.
limit	No	Maximum results. Behaviour differs per endpoint, see below.

limit is not the same on both

Endpoint	Omitted or 0	Accepted range
/memory/recall	No truncation, every selected fact is returned	Any positive integer
/memory/search	No truncation	Up to 200. Higher is rejected as a validation error

Scope in practice

The default is deliberately narrow. A call with no thread_id and no scope reads only agent-global facts, not the whole history. This catches people out:

# Only thread-less facts
{"query": "What desk setup does Bob use?"}

# That one thread, plus thread-less facts
{"query": "...", "thread_id": "6f2c..."}

# Everything this agent knows
{"query": "...", "scope": "agent"}

Examples

Recall

curl -X POST https://eu.recalld.ai/v1/agents/$AGENT_ID/memory/recall \
  -H "Authorization: Bearer $RECALLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What desk setup does Bob use?",
    "scope": "agent"
  }'

Narrowing to one document

source_kind, author and path restrict which sources the answer may come from. They are applied before ranking, so the query still decides the order: it just ranks within the subset. They combine with thread_id and scope rather than replacing them.

The common case is a chat where the user has uploaded several files into one thread and then asks a question about one of them. Send the filename as path at ingestion, and pass the same value at retrieval.

curl -X POST https://eu.recalld.ai/v1/agents/$AGENT_ID/memory/recall   -H "Authorization: Bearer $RECALLD_API_KEY"   -H "Content-Type: application/json"   -d '{
    "query": "what is the notice period for termination?",
    "thread_id": "'$THREAD_ID'",
    "path": "contract-b.pdf"
  }'

A filter that matches nothing returns no results. To discover the values an agent actually holds, call GET /v1/agents/{agent_id}/filters, optionally with ?thread_id=. It returns the distinct source_kinds, authors and paths that agent has ingested.

The same three filters are available as query parameters on GET /v1/agents/{agent_id}/facts for browsing without a query. That endpoint lists in insertion order and does no ranking, so use it to enumerate what is stored, not to answer a question.

Including sources

Both endpoints always return facts. Send include_sources: true to also get sources: the original text the returned facts were extracted from. Use it when you need to show a user where an answer came from, or when you want the surrounding wording rather than the distilled fact.

Each source appears once, even when several facts came from it.
Sources follow the order of the facts: the source of the first fact comes first.
For a long document, only the passages behind the returned facts are included, joined with [...].
Each fact carries source_id, the id of its entry in sources.

curl -X POST https://eu.recalld.ai/v1/agents/$AGENT_ID/memory/recall \
  -H "Authorization: Bearer $RECALLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What desk setup does Bob use?",
    "scope": "agent",
    "include_sources": true
  }'

{
  "facts": [
    {"index": 1, "id": "f-1", "text": "Bob uses a standing desk.", "kind": "KNOWLEDGE",
     "source_id": "s-1", "event_date": "2026-03-02T00:00:00Z"}
  ],
  "sources": [
    {"index": 1, "id": "s-1", "kind": "USER", "author": "bob",
     "content": "I finally switched to a standing desk last week.",
     "event_date": "2026-03-02T00:00:00Z"}
  ]
}

Errors

Status	Cause
400	Missing `query`, `limit` outside the accepted range for that endpoint, or the removed `mode` field (use `include_sources`).