Recall memory

Search memory with a natural-language query and get ranked hits, confidence, and usage.

POST /recall

Recall memory

cURL

curl --request POST \
  --url https://api.getmetacognition.com/recall \
  --header 'Content-Type: application/json' \
  --data '
{
  "scope.org_id": "<string>",
  "scope.session_id": "<string>",
  "q": "<string>",
  "mode": {},
  "top_k": 123,
  "include_timeline": true
}
'

200

{
  "hits.turns": [
    {}
  ],
  "hits.observations": [
    {}
  ],
  "hits.entities": [
    {}
  ],
  "confidence": 123,
  "timeline": {},
  "mode": "<string>",
  "usage": {}
}

This is the REST version of tex.recall. Use it before generation to get the memory your model should read. For mode, top_k, and confidence, see Recall and ranking.

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Body

{
  "scope": {
    "org_id": "org_...",
    "session_id": "chat-1"
  },
  "q": "what does the user prefer?",
  "mode": "active",
  "top_k": 5,
  "include_timeline": false
}

scope.org_id · string · required

Your org id. Minimum length is 1 character. The server still uses the JWT’s org_id claim for tenancy; this field is required for request validation.

scope.session_id · string

Session to search. Optional. Falls back to the JWT’s session_id.

q · string · required

Natural-language query. min_length=1.

mode · "active" | "deep" · default: "\"active\""

Retrieval depth. See Recall and ranking.

top_k · integer

Hits to return across all kinds. Defaults to 15 (active) / 25 (deep). Request validation accepts 1 <= top_k <= 50; runtime caps the final value at 30.

include_timeline · boolean · default: "false"

Attach a chronological summary string to the response.

Response — 200

hits.turns · array

Ranked raw turns.

hits.observations · array

Atomic facts.

hits.entities · array

Linked entities. Each entity has {id?, label, score}. This is different from turns and observations.

confidence · number

Calibrated [0, 1].

timeline · string | null

Pre-rendered chronological summary, set only when include_timeline=true.

mode · string

Echoes request mode.

usage · object

{tokens_in, tokens_out} for this call.

Hit fields

{
  "id": "c9fcfbf51b03bbc3...",
  "text": "[user] I'm allergic to shellfish.",
  "score": 0.42,
  "kind": "turn",
  "timestamp": "1778061473326"
}

Example

cURL

curl -X POST https://api.getmetacognition.com/recall \
  -H "Authorization: Bearer $JWT" \
  -H 'content-type: application/json' \
  -d '{
    "scope": {"org_id":"org_…","session_id":"chat-1"},
    "q": "any food restrictions?",
    "top_k": 3
  }'

Response

{
  "hits": {
    "observations": [],
    "turns": [
      {
        "id": "c9fcfbf5...",
        "text": "[Date: 2026-05-08T14:00:00Z] [user] I'm allergic to shellfish",
        "score": 0.4268,
        "kind": "turn",
        "timestamp": "1778061473326"
      }
    ],
    "entities": []
  },
  "timeline": null,
  "confidence": 0.067,
  "mode": "active",
  "usage": { "tokens_in": 6, "tokens_out": 27 }
}