Search and adjacent chunks
Pagination follows the shared Pagination and truncation contract (D154).
Search returns evidence, not facts. A claim is what one source said; a chunk
is a passage of a source document. Neither is a statement of what the memory
holds true. For that, use facts_context
or the lookup routes.
Each search exists in two forms. The GET form puts the query in the URL; the
POST form puts it in the body. A query is often a person's own words, and a
URL is written to access logs, kept by proxies and saved in browser history.
The POST form keeps the query text out of all three, so prefer it for
anything a person typed. The GET form stays for existing clients; both
return the same result and cost the same.
All six routes need the read scope. Base URL, authentication and error shapes are described in
HTTP API conventions.
How search works
- Nominate. The chosen channel ranks candidate ids:
semanticembeds the query and compares vectors;bm25ranks by keyword. Only current testimony is nominated for claims. - Confirm. Each candidate is re-read from the database. Anything that no
longer holds — a deleted version, a forgotten source — is dropped, and the
number dropped is reported in
dropped_by_hydration.
A search that finds nothing returns 200 with negative.kind known_empty.
Limiting search to certain documents
The POST forms accept a documents filter with the same fields as
POST /documents/search:
family, authors, recipients, created_from/created_to,
modified_from/modified_to, language, thread_ref, doc_ids and
tags ({"all": [...], "any": [...], "none": [...]}, the document's
tags). The filter decides which results are
included:
- chunks match when the chunk's document version matches;
- claims match when at least one place the claim occurs is in a matching
document version. A claim that repeats across a document's versions is
checked against each version separately, so
authors: ["alice"]finds the claim through the version Alice wrote even if a later version names someone else. The filter only decides which claims are included: each returned claim looks exactly as it does without a filter, with thechunk_id, offsets andevidence_spansof the passage it was first extracted from.
Deleted documents and deleted versions never match. The filter is applied
while ranking, before the k best are chosen, so asking for k: 10 returns
up to ten matching results even when better-scoring results from other
documents exist.
tags is tested on the document, not on a version: every version of a
document carries its current tags, also when time reads an older edition.
A tag that is not registered refuses the search with 422 unknown_tag,
naming every unregistered tag (the Python client raises
remember.UnknownTag); nothing is searched.
With a time scope, the filter and the scope must hold for the same
version. A claim that occurs in two versions of a document with declared
effective periods is returned only through a version that both matches the
filter and is in force for the scope, never by combining one version that
matches with another that is in force.
When a filtered search completes and finds nothing, negative.explanation
says which case it was: no live document matches the filter, or matching
documents exist but none of them says anything relevant to the query. A
search stopped by its work bound reports negative.kind boundary
instead, whatever the filter matched.
For "everything about Project X from emails from Alice": find the right
Alice with POST /documents/search and filters.authors; if several people
match, narrow to an address. Then search with
{"query": "Project X", "documents": {"authors": ["[email protected]"]}}.
Each returned claim was found in a version Alice wrote; its cited evidence is
where the claim was first extracted, which can be another version of the same
document.
Every result cites the document it came from.
The three context operations take the same filter as documents; see
The documents filter.
Reading text as of a date
The POST forms also accept time, the same scope the assured operations
take: {"mode": "current"} (the default), {"mode": "at", "at": …},
{"mode": "overlap", "from": …, "to": …} (both ends included) or
{"mode": "history"} (any point up to now). It matters for documents whose
versions have declared effective periods:
for those, only versions in force for the scope are searched. A document
without declared periods is searched in its served version, its newest
processed one, whatever time says, so leaving time out changes nothing
for such a corpus.
Like the documents filter, the scope is applied while ranking, before the
k best are chosen. What changes in the results for a document with
declared periods:
- Every result names its version. A chunk's
version_id,representation_idand offsets are those of the selected version, andeffectivelists that version's in-force intervals.served_versionisfalsewhen the selected version is not the document's served version. - A claim is shown where it is in force. A claim that occurs in several
versions is returned once, with one entry in
occurrencesper selected version, earliest period first. Its top-levelchunk_id, offsets,evidence_spans,version_id,representation_idandeffectiveare those of the first occurrence, not of the passage the claim was first extracted from. - Not in force, not returned. Under
current, an edition that is not in force yet, or no longer, contributes nothing. When two editions are in force at once, both are searched and each result says which it came from. - Still processing. While the version in force is still being processed,
its document contributes nothing; it never falls back to the version it
replaces. The envelope's
freshness.scope_pendinglists such documents (at most 50 ids, with acount) among the documents the results name and thedoc_idsyourdocumentsfilter names, so "nothing is in force" can be told from "not ready yet".
temporal_scope reports the mode applied. The GET forms take no time
and always read current.
GET /search/claims
Search claims.
Parameters
| Name | In | Type | Required | Default | Constraints |
|---|---|---|---|---|---|
query | query | string | yes | ||
k | query | integer | no | 10 | 1 to 400. |
channel | query | semantic | bm25 | no | semantic |
Response
200 with an Envelope of grain evidence.
evidence holds up to k EvidenceResult
entries in rank order.
Errors
| Status | detail | Cause |
|---|---|---|
422 | validation list | query missing, k out of range, or an unknown channel. |
503 | model provider unavailable | The embedding call failed (semantic channel). Retry with back-off. |
Example
curl -s -G "$REMEMBER_API_URL/search/claims" \
-H "Authorization: Bearer $REMEMBER_API_KEY" \
--data-urlencode "query=billing migration cutover date" \
--data-urlencode "k=20"from remember import Client
memory = Client()
envelope = memory.search_claims(query="billing migration cutover date", k=20)
for claim in envelope.evidence:
print(claim.claim_text, claim.document_title)POST /search/claims
Search claims, with the query in the body.
Request body
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
query | string | yes | 1 to 4,096 characters. | |
k | integer | no | 10 | 1 to 400. |
channel | semantic | bm25 | no | semantic | |
documents | DocumentSearchFilters | no | Only results found in matching document versions; see Limiting search to certain documents. | |
time | object | no | {"mode": "current"} | Only text in force for the scope; see Reading text as of a date. |
Unknown fields are rejected.
Response
As for GET /search/claims.
Errors
As for GET /search/claims, plus 422 for an empty or over-long query,
an unknown field, a malformed time (an unknown mode, a missing instant,
an instant without a time zone, or to before from), an empty, repeating
or too long documents.tags list, or 422
{"code": "unknown_tag", "message": …, "tags": [...]} when
documents.tags names tags that are not registered.
Example
curl -s -X POST "$REMEMBER_API_URL/search/claims" \
-H "Authorization: Bearer $REMEMBER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "billing migration cutover date", "k": 20, "channel": "bm25"}'The remember Python client's search_claims uses GET, and the POST form
when you pass documents or time.
GET /search/chunks
Search source chunks: passages of the documents themselves.
Parameters
| Name | In | Type | Required | Default | Constraints |
|---|---|---|---|---|---|
query | query | string | yes | ||
k | query | integer | no | 10 | 1 to 400. |
channel | query | semantic | bm25 | no | semantic |
Response
200 with an Envelope of grain evidence. chunks holds up to k
ChunkEvidenceResult entries in
rank order, each with the chunk text, its offsets in the document's converted
Markdown, and the document it belongs to.
Errors
As for GET /search/claims.
Example
curl -s -G "$REMEMBER_API_URL/search/chunks" \
-H "Authorization: Bearer $REMEMBER_API_KEY" \
--data-urlencode "query=rollback plan" \
--data-urlencode "channel=bm25"envelope = memory.search_chunks(query="rollback plan", channel="bm25")
for chunk in envelope.chunks:
print(chunk.document_title, chunk.char_start, chunk.chunk_text[:80])POST /search/chunks
Search source chunks, with the query in the body.
Request body
SearchRequest, as for
POST /search/claims.
Response
As for GET /search/chunks.
Errors
As for POST /search/claims.
Example
curl -s -X POST "$REMEMBER_API_URL/search/chunks" \
-H "Authorization: Bearer $REMEMBER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "rollback plan", "k": 10}'curl -s -X POST "$REMEMBER_API_URL/search/chunks" \
-H "Authorization: Bearer $REMEMBER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "daily allowance", "time": {"mode": "at", "at": "2026-02-01T00:00:00Z"}}'The remember Python client's search_chunks uses GET, and the POST form
when you pass documents or time.
GET /chunks/{chunk_id}/adjacent
Return a chunk together with its neighbours in document order, so you can read a search hit in context.
Parameters
| Name | In | Type | Required | Default | Constraints |
|---|---|---|---|---|---|
chunk_id | path | UUID | yes | ||
window | query | integer | no | 1 | 1 or 2. How many chunks on each side. |
The neighbours come from the same version of the same document as the target chunk. The target may be a chunk of any version that is not deleted and is fully processed, not only the served one, so a passage returned for an older or future edition can be read in context.
Response
200 with an Envelope of grain evidence. chunks holds up to
2 × window + 1 chunks in document order, the target included. An unknown or
no longer visible chunk_id gives negative.kind unknown_entity. If the
target exists but none of the chunks can be confirmed, negative.kind is
known_empty.
Errors
| Status | detail | Cause |
|---|---|---|
422 | validation list | chunk_id is not a UUID, or window is not 1 or 2. |
Example
curl -s "$REMEMBER_API_URL/chunks/$CHUNK_ID/adjacent?window=2" \
-H "Authorization: Bearer $REMEMBER_API_KEY"envelope = memory.adjacent_chunks(chunk_id=chunk_id, window=2)POST /chunks/adjacent
Return a chunk and its neighbours, with the chunk id in the body.
Request body
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
chunk_id | UUID | yes | ||
window | integer | no | 1 | 1 or 2. |
Unknown fields are rejected.
Response
As for GET /chunks/{chunk_id}/adjacent.
Errors
422 for a missing or malformed chunk_id, a window other than 1 or 2, or
an unknown field.
Example
curl -s -X POST "$REMEMBER_API_URL/chunks/adjacent" \
-H "Authorization: Bearer $REMEMBER_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"chunk_id\": \"$CHUNK_ID\", \"window\": 1}"The remember Python client's adjacent_chunks uses the GET form.