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.
mode	No	`facts` (default) returns extracted facts. `sources` returns the original excerpts instead.
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.

Sources mode

mode: "sources" switches the return collection from extracted facts to the original message excerpts they came 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.

Errors

Status	Cause
400	Missing `query`, or `limit` outside the accepted range for that endpoint.