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.
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.