RememberStackremember.dev/docs

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

  1. Nominate. The chosen channel ranks candidate ids: semantic embeds the query and compares vectors; bm25 ranks by keyword. Only current testimony is nominated for claims.
  2. 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 the chunk_id, offsets and evidence_spans of 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_id and offsets are those of the selected version, and effective lists that version's in-force intervals. served_version is false when 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 occurrences per selected version, earliest period first. Its top-level chunk_id, offsets, evidence_spans, version_id, representation_id and effective are 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_pending lists such documents (at most 50 ids, with a count) among the documents the results name and the doc_ids your documents filter 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

NameInTypeRequiredDefaultConstraints
queryquerystringyes
kqueryintegerno101 to 400.
channelquerysemantic | bm25nosemantic

Response

200 with an Envelope of grain evidence. evidence holds up to k EvidenceResult entries in rank order.

Errors

StatusdetailCause
422validation listquery missing, k out of range, or an unknown channel.
503model provider unavailableThe 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

SearchRequest:

FieldTypeRequiredDefaultConstraints
querystringyes1 to 4,096 characters.
kintegerno101 to 400.
channelsemantic | bm25nosemantic
documentsDocumentSearchFiltersnoOnly results found in matching document versions; see Limiting search to certain documents.
timeobjectno{"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

NameInTypeRequiredDefaultConstraints
queryquerystringyes
kqueryintegerno101 to 400.
channelquerysemantic | bm25nosemantic

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

NameInTypeRequiredDefaultConstraints
chunk_idpathUUIDyes
windowqueryintegerno11 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

StatusdetailCause
422validation listchunk_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

FieldTypeRequiredDefaultConstraints
chunk_idUUIDyes
windowintegerno11 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.