Search
The two shapes a search answers in, the date and place bounds that pick between them, and the lookups beside search.
/v1/memory/search takes a question in plain words and searches one end user's memory two
ways at once: by the words used and by meaning. It then keeps what the question needs. It answers in one of two
shapes.
The brief
With no scope and no after, search returns a brief: everything memory has for the question, ready to put
in a prompt.
| Field | What it holds | When present |
|---|---|---|
query | The question as asked. | always |
found | How many passages are in hits. | always |
notes | How to read what follows, written for the model. For example, that the assistant's own suggestions are not the person's words. | when one applies |
known | What is known now: one line per subject and attribute, every value as stated, newest first, each with the day it was said. | once the end user's records are folded |
worked_out | Lines computed over the records, such as a count, or a conflict between two statements. | when the question calls for one |
facts | The records the question needs, each one dated line with its id and the source passage it was read from. | once records exist |
hits | The passages themselves, up to 1,400 characters each, with their id, path, roles (who spoke) and content: "stored". | always, possibly empty |
held | false when memory's own check says it does not hold the answer. | when filtering ran |
Right after an add, before records are read, a brief holds query, found, perhaps notes, and hits.
The ranked list
With a scope or an after, search returns a ranked list of passages inside that window, with the records
in the same window:
query,found,hits, andfactswhen any match.- No
known,worked_out,notesorheld.
scope is a path prefix. Content you add lives under passages/memory/messages, passages/memory/documents and
passages/memory/notes, so a scope of passages/memory/documents searches only documents.
Dates
beforeasks the question as of a day. Nothing said after it is used, and words like "last week" in the question are read against that day. A search with onlybeforestill returns a brief.afterkeeps only memory from that day on, and returns the ranked list.
Both take YYYY-MM-DD or a full ISO time. A question with no before is asked as of today.
held
When search filters what it found, it also judges whether memory holds the answer. held: false means it does
not. Have your model say it does not know rather than guess. held is absent when no filtering ran.
Cost
A search makes at most one model call, to keep only what the question needs. When your organisation's daily
budget is spent, search answers with the unfiltered ranking instead, which makes no call, and held is absent.
Nothing is refused.
Lookups beside search
Search ranks. Some questions are better answered by a lookup that does not rank. None of these makes a model call.
| Route | Use it for |
|---|---|
grep | An exact phrase, an id or an error code, which meaning would blur. Case is ignored. |
latest | The newest passages, or everything between two dates. "What happened last" is not a similarity. |
around | The passages either side of one you already hold, in the same conversation. |
read | One passage or file, whole, by the path a result gave you. |
ls | What exists under a path, before you read. |
history | Every value recorded for one subject. |
Every result carries an address, id and path, so the next call can be a lookup, not another search.
Related
- Search reference: every field and error.
- Using memory with an LLM: how to lay the brief out in a prompt.
- Records & reading: why
factsandknownappear later thanhits.