Skip to main content
← All use cases
API reference

​
The scenario

Search answers “what is relevant to this question”. It cannot answer “what is in here”, and those are different questions — the second one is what you need when recall is disappointing and you are trying to work out whether the memory is missing or merely unranked. What this recipe shows that no other does: reading memories without a query at all. Everything else in this cookbook searches.

​
Step 1 — Page through it

total is the number people want first and search will never give you.

​
Step 2 — Filter without ranking

memory_type is one of fact, note, experience or summary; anything else is a 422. state="invalidated" is the interesting one: it lists what has been superseded — a view of what the space used to believe, which no search returns because superseded memories are excluded from recall by design.

​
Step 3 — Follow a memory back to its document

The list does not carry document_id; a retrieve result does, and only on a fact. A note is a synthesis that can span several documents, so its document_id is null and its source_ids point at the facts instead — which is why this asks for the facts with prefer_observations=False.

​
Step 4 — Remove a document and everything it produced

One call removes the file and every memory extracted from it. That is what makes “unpublish that outdated policy” a single operation instead of a hunt through search results.

​
Evals

  1. Upload one document, note memory_count on it.
  2. list_memories(memory_type="fact", prefer_observations=False) and confirm total moved by that amount. memory_count counts the facts extracted from the file; the default list counts notes too and hides facts a note covers, so its total moves by a different number, by design.
  3. Delete the document, list again, confirm total came back down.
  4. Search for something only that document said. Empty is the correct answer — if it still returns, the deletion did not cascade and that is worth reporting.

​
Guardrails

Deleting a document is irreversible and takes its memories with it. That is usually what you want and it is never undoable. Check memory_count first so the blast radius is a number you have seen.
  • The list dedups by default. prefer_observations=True hides raw facts a consolidation already covers, so total is smaller than the raw row count. Pass False to see the evidence layer underneath.
  • Browsing is not free of cost in attention. A space with 40,000 memories cannot be read; use it to spot-check extraction, not to audit a corpus.
  • offset paging drifts under active writing. For a full export, use Take everything with you instead.