Skip to content
DashboardGet API key

Recall facts by meaning

View .md
POST

Embed the query and return the closest facts in the scope, ranked by cosine similarity.

Scope goes in the body, like POST /v1/memory: scope plus the matching id.

Without minScore, a scope always answers with its limit closest facts however distant they are — a search that found nothing relevant is indistinguishable from one that found the right thing. Set minScore when your code branches on "did I know this?".

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Body

application/json

  • querystringrequired

    What to recall. Max 8,192 bytes. Phrase it as the fact you hope to find, not as a keyword: the match is semantic.

  • scopestring

    Which namespace a memory belongs to. Scopes are isolated: a search in one never returns a memory from another.

    • project: shared by the whole project. What the agent knows in general.
    • contact: what the agent knows about one person, across every conversation with them.
    • conversation: what the agent knows about one inbox thread.

    Defaults to project everywhere. contact and conversation require the matching id.

    One ofprojectcontactconversation
  • contactIdstring

    Required when scope is contact.

  • conversationIdstring

    Required when scope is conversation.

  • limitinteger

    Maximum hits to return, closest first.

    Default5
    Limitsmin 1 · max 20
  • minScorenumber

    Drop hits below this similarity. Without it every scope returns its limit closest facts, however far away they are — an empty-handed search still answers with something. Set it (0.3 or above is a reasonable floor) when "nothing relevant" must be distinguishable from "the least irrelevant thing I hold".

    Limitsmin 0 · max 1

Responses

200Matching facts, closest first. An empty `items` means nothing cleared `minScore`.
  • itemsobject[]required
    6 properties
    • idstringrequired
    • textstring

      The remembered text.

    • metadataobject
      1 properties
      • {key}string
    • scorenumber

      Cosine similarity to the query, 0 to 1, higher being closer. Present on search results only — a list or a single read has no query to score against.

    • createdAtstring<date-time>required
    • expiresAtstring<date-time>
400Invalid body or a scope without its id.
  • codestringrequired
  • messagestringrequired
  • detailsobject
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject