Skip to main content
Reading comes in two shapes. Ask a question and get the facts that answer it, ranked. Or read a profile whole, unranked, when you want to see everything it holds.

​
Ask a Question

URL-encode the profile id in the path. A profile_id is free-form and often carries reserved characters — caller:+13128675309 has both : and + — so percent-encode it when you interpolate it into a request path (caller%3A%2B13128675309), or the route can be changed or truncated.
Results come back in rank order, most relevant first. Rank is the signal to build on — read the list in the order it arrives rather than filtering on the score field:
There is no model in the recall path. Recall ranks and returns facts; it does not compose an answer. Putting those facts in front of your own agent is the last step, and it stays yours.

​
Prime a Session Before the First Turn

recall answers questions, which means your agent has to have one. At the start of a session it does not: nobody has said anything yet, and “what do we know about this person?” is a weak query that returns ranked fragments rather than a picture. That is the job summary does — the whole profile as one card, precomputed, no query and no retrieval at request time:
A card is generated in the background. is_stale means newer memories have landed since the card was written — ordinary, and the card is still usable.
On the first read, a card may not exist yet. For a profile whose summary has not been generated, text and generated_at come back null — the first read schedules one, so read again shortly. Guard for a non-null text before templating it into a prompt; if it is null, open the session without a card rather than injecting null.
Three things follow from a precomputed card:
  • It is fast enough for turn zero. A voice agent cannot spend a retrieval round-trip before greeting someone.
  • It has a stable shape. A card is a predictable block to template into a system prompt. Ranked facts vary in length and content with every query, which is awkward to budget context for.
  • It costs less. Opening every session with “tell me about this person” pays for full multi-strategy retrieval to answer a question whose result barely moves between sessions.
So the two reads divide by moment rather than by preference: You can steer how these cards read with summary instructions, set once per namespace.

​
Read a Profile Whole

Everything one profile holds, most recent first:
Listing depth is bounded: page[number] × page[size] cannot exceed 10,000. To reach older memories, narrow with session_id rather than paging deeper.
Don’t stop on a short page. A page can hold fewer than page[size] entries while more results remain, so a client that stops when data.length < page[size] silently drops the rest. Advance page[number] until it passes meta.total_pages (or you have read meta.total_results). Both listings behave this way.A page is also a snapshot: counts and order shift as writes land, so paging through a namespace that is being written to can repeat or miss an entry at a boundary. If that matters, page when writes are quiet, or de-duplicate on id as you go.
session_id narrows to memories that came from that one session. Some memories draw on several sessions and belong to none of them, so they appear only in the unfiltered listing. A filtered read is not a subset you can page through to see everything.

​
Who Is in a Namespace

Which profiles hold memories, and how many each:
Takes the same page[number] and page[size]. A profile appears once its first memory is extracted, so one whose ingest is still running is not listed yet.
  • Writing memories — ingest, remember, and tracking the operation
  • Sources — what a profile stored, and tracing a memory back to it
  • Agent Memory — namespaces, profiles, and how they are created