Memory
How memory works
Sources, the graph, and what retrieval actually returns.
A memory is one graph belonging to one person or team. In the API it is an
office, identified by an officeId. The two words describe the same object,
and you will see both in SDK signatures.
The shape of it
A source is connected
The user authorizes Gmail, Calendar, Drive, Notion, WhatsApp, Slack, or uploads an export. Authorization always happens in the dashboard. An agent can produce the link, but never the grant.
Contents are ingested and embedded
Items are pulled, chunked, embedded, and written into the graph with their provenance intact.
cortex_statusreports the backlog while this runs.Agents read and write
Retrieval fuses vector, full-text and graph expansion. Facts an agent learns go back in through
cortex_remember, linked to whatever they were derived from.
Nearest matches, not a thresholded set
This is the single most important thing to understand before you build on retrieval.
A query always returns the closest things in the graph. It does not return nothing when the answer is absent, it returns near-misses. So "the model got a weak answer" and "the source that would answer this was never connected" look identical if you only read the results.
Mitosis makes the difference explicit. A response can carry one of three blocks:
source_gap: the answer's source is not connected
The memory holds data, but not the kind that could answer this question. The
block names the sources that would, says what each one answers, and carries a
cta with a connect link.
possible_source_gap: results may be near-misses
Results came back, but they may not be an answer. Treat the response as provisional rather than authoritative.
memory_state: nothing is connected at all
No sources exist yet, so an empty result reflects absent data rather than a failed search.
A result carrying none of these blocks means the answer is genuinely not in the memory, not merely unretrieved. That is the case where "I don't know" is the correct thing for your agent to say.
Provenance
Every result carries citations as universal ids, plus cited_graph_url, a
deep link that opens the user's own graph with exactly those nodes highlighted.
When you write a fact back with cortex_remember, pass the universal ids it came
from as source_universal_ids so the new node inherits provenance edges instead
of floating free.
Which retrieval call to use
| Call | Use it when |
|---|---|
cortex_ask | Almost always. Fuses vector, full-text and graph expansion, and answers in natural language with citations. |
cortex_recall | You specifically want nearest-neighbour matches on meaning, returned as source excerpts. |
cortex_manifest | You need counts and source names. An index, never content. |