Core concepts

Threads and facts

Threads group related content inside an agent. Facts are what Recalld actually stores and returns after extraction.

Threads

A thread is one conversation, session, or document set. Attaching input to a thread keeps it grouped, and lets retrieval narrow to that conversation instead of the agent's whole history.

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

You do not have to create threads up front. Passing a thread_id to ingest is enough, and omitting it entirely writes agent-global memory that every thread can see.

Thread-less facts are global

Content ingested without a thread_id produces facts attached to no thread. Those are visible from every thread of that agent. This is the right place for durable truths about a user, and the wrong place for anything specific to one conversation.

Reading a thread back

GET /v1/agents/{agent_id}/threads/{id}/messages returns the original messages projected from stored sources, not the extracted facts. Use it to show conversation history; use retrieval to answer questions.

Facts

Ingestion does not store your text as-is. It extracts discrete facts and compares them with existing memory. When new information conflicts with an older fact, Recalld can supersede it. Retrieval selects relevant facts instead of returning the full conversation history.

Fact kinds

Kind	Retrieval behaviour
KNOWLEDGE	Returned when semantically relevant to the query. The default for most extracted content.
RULE	Always included in retrieval, relevance aside. Use for standing instructions.
PREFERENCE	Returned when relevant to a choice. A soft weight rather than a hard constraint.

Source trust

Every fact remembers the kind of source that created it. A source can only alter facts created by an equal or lower trust source, which stops a scraped document from quietly overwriting something a user told you directly.

Source	Trust	Can overwrite
SYSTEM	100	Immutable. Nothing can alter a SYSTEM fact, including SYSTEM.
USER	80	USER and below
AGENT	60	AGENT and below
TOOL	40	TOOL and below
DOCUMENT	20	DOCUMENT and CODE
CODE	10	CODE only

Writing facts directly

POST /v1/agents/{agent_id}/facts stores a fact verbatim, skipping extraction. It still costs credits, because the text has to be embedded. Supply source so the trust rules above apply.

curl -X POST https://eu.recalld.ai/v1/agents/$AGENT_ID/facts \
  -H "Authorization: Bearer $RECALLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "'"$AGENT_ID"'",
    "text": "Bob works in the Berlin office.",
    "source": "USER",
    "kind": "KNOWLEDGE"
  }'

Updating a fact regenerates its embedding and is subject to the same trust check: the source you send must be at least as trusted as the one that created the fact.