Skip to Content
Recall
REST API

Search

Hybrid keyword and vector search over current facts and document chunks. No LLM call.

POST /v1/search

Searches one container with SQLite FTS5 and sqlite-vec, merged with reciprocal rank fusion. Only current facts are searched. See hybrid search for how ranking works.

NameTypeRequiredDefaultLimits
containerstringnoserver default1 to 128 characters
qstringyes1 to 2,000 characters after trimming
limitintegerno101 to 100
includearray of "memories", "chunks"no["memories"]An empty array means ["memories"]
curl -X POST https://recall.zakiego.com/v1/search \
  -H "Authorization: Bearer $RECALL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"container":"alice","q":"sepatu lari","limit":5,"include":["memories","chunks"]}'
{
  "container": "alice",
  "q": "sepatu lari",
  "results": [
    {
      "type": "memory",
      "id": "mem_...",
      "text": "Prefers Puma running shoes",
      "kind": "dynamic",
      "keywords": "shoes sneakers running footwear sepatu lari merek brand puma",
      "sourceDocumentId": "doc_...",
      "createdAt": 1762675200000,
      "score": 0.03279,
      "ftsRank": 1,
      "vecRank": 1,
      "similarity": 0.87,
      "people": [{ "id": "per_...", "name": "Clara Simmons" }]
    },
    {
      "type": "chunk",
      "id": "chk_...",
      "text": "I switched to Puma running shoes.",
      "documentId": "doc_...",
      "documentTitle": "I switched to Puma running shoes.",
      "idx": 0,
      "score": 0.01639,
      "vecRank": 1,
      "similarity": 0.84
    }
  ],
  "timingMs": 9
}

Fields on each hit:

FieldMeaning
typememory or chunk
textThe fact, or the chunk text
scoreReciprocal rank fusion score: the sum of 1 / (60 + rank) over the lists the hit appeared in. Higher is better
ftsRankPosition in the keyword results. Missing when the keyword search didn't return it
vecRankPosition in the vector results. Missing when the vector search didn't return it
similarity1 minus the cosine distance. Only present with vecRank
kind, keywords, sourceDocumentId, createdAtMemory hits only
eventDate, eventPrecision, dueDate, duePrecisionMemory hits only. The fact's dates, or null
peopleMemory hits only. The people the fact mentions, as { id, name }. Empty when it names nobody
documentId, documentTitle, idxChunk hits only. idx is the chunk's position in its document

With both kinds included, memories and chunks are merged by score and cut to limit. timingMs includes embedding the query.

StatusWhen
200Results, possibly an empty list
400Missing or empty q, or a field out of range

On this page