Core concepts

Agents

An agent owns memory. It is the boundary that decides what a retrieval call can possibly see.

The model

Every fact Recalld stores belongs to exactly one agent. Retrieval never crosses that boundary, so two agents on the same account cannot read each other's memory. If you want isolation between your end users, give each one an agent.

Scope	Holds	Shared with
agent	Everything written for one agent	Nothing else
thread	One conversation or session inside an agent	Other threads on request, see scope
task	A pool several agents write into and read from	Every agent using the same `task_id`

Creating an agent

curl -X POST https://eu.recalld.ai/v1/agents \
  -H "Authorization: Bearer $RECALLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "support-bot"}'

name is required and is for your benefit only. Nothing in retrieval reads it.

Choosing models

Each agent runs three LLM steps and one embedding model. You can set any of them when you create the agent.

Field	Runs on	Does
`llm_models.decompose`	Ingestion	Breaks what you write into facts and plans the lookups for related stored facts
`llm_models.evaluate`	Ingestion	Compares new facts with stored ones and decides what to add, update, or supersede
`llm_models.select_facts`	Recall	Picks the facts that answer the request. Search does not use an LLM
`embedding_model`	Ingestion and retrieval	Turns facts and queries into vectors. Cannot be changed after the agent is created

curl -X POST https://eu.recalld.ai/v1/agents \
  -H "Authorization: Bearer $RECALLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-bot",
    "llm_models": {
      "decompose": "openai-gpt-6-luna",
      "evaluate": "openai-gpt-6-luna",
      "select_facts": "openai-gpt-6-luna"
    },
    "embedding_model": "gemini-embedding-002-vertex"
  }'

Each id must be a memory model listed by GET /v1/models for the region. A field you leave out uses your account's default model, set in Settings, and without one, Recalld's default. The LLM steps can be changed later from the agent in the dashboard.

Plan limits

The Free plan runs default models only. Creating an agent with another model is refused with 400. If your plan later changes to Free, an agent set to other models runs on the defaults until you upgrade.

Check which models ran

Responses from the memory routes under /v1/agents/{agent_id}/, such as ingestion, recall, and search, carry an X-Recalld-Models header. It names the models that request ran with, after your account, agent, and plan settings were applied:

X-Recalld-Models: decompose=openai-gpt-6-luna, evaluate=openai-gpt-6-luna, select_facts=openai-gpt-6-luna, embedding=gemini-embedding-002-vertex

When the exact model matters, for example in an evaluation, compare it with what you asked for. Defaults can change, so the header is the record of what ran.

How many agents

Two patterns cover almost everything:

One agent per end user. Right when memory is personal and must never leak between people. Use threads inside it for individual sessions.
One agent per assistant. Right when memory is about a shared domain, for example a support bot that should accumulate product knowledge across every conversation.

Do not create an agent per conversation. That is what threads are for, and it throws away the cross-session recall that makes memory worth having.

Shared task memory

Passing task_id on ingest and retrieval opts that call into a shared pool. Every agent sending the same task_id reads and writes the same facts, on top of its own private memory. Use it when several agents collaborate on one job and need each other's findings.

Deleting an agent

curl -X DELETE https://eu.recalld.ai/v1/agents/$AGENT_ID \
  -H "Authorization: Bearer $RECALLD_API_KEY"

Deletion removes the memory too

Deleting an agent discards its facts, threads, and sources. There is no undo and no export step built into the call.