> ## Documentation Index
> Fetch the complete documentation index at: https://metacognition-fdc534de-master.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Recall relevant context

> Query memory with natural language and get ranked hits, confidence, and usage.

Use **`tex.recall`** before you call your model. It returns the memory that best matches the current user message.

For **`mode`**, **`top_k`**, and **`confidence`**, read [Recall and ranking](/concepts/retrieval). This page lists the Python fields.

```python theme={null}
RecallResponse = tex.recall(
    q: str,
    *,
    session_id: str,
    mode: "active" | "deep" = "active",
    top_k: int | None = None,
    include_timeline: bool = False,
) -> RecallResponse
```

<Note>
  Call recall directly on the client: `tex.recall(...)`. There is no `tex.recall.search(...)`.
</Note>

## Parameters

<ParamField path="q" type="str" required>
  Natural-language query. The user's latest message usually works well.
</ParamField>

<ParamField path="session_id" type="str" required>
  Session to search. Use the same `session_id` you wrote with.
</ParamField>

<ParamField path="mode" type="&#x22;active&#x22; | &#x22;deep&#x22;" default="&#x22;active&#x22;">
  Retrieval depth. See [Recall and ranking](/concepts/retrieval).
</ParamField>

<ParamField path="top_k" type="int">
  Number of hits across all kinds. Defaults to **15** in `active` mode and **25** in `deep` mode. The server caps the final value at **30**.
</ParamField>

<ParamField path="include_timeline" type="bool" default="false">
  When true, the response includes a pre-rendered **`timeline`** string (not a structured list).
</ParamField>

## Returns

<ResponseField name="hits.turns" type="list[RecallHit]">
  Raw conversation turns most relevant to `q`.
</ResponseField>

<ResponseField name="hits.observations" type="list[RecallHit]">
  Small facts extracted from past turns, such as preferences or decisions.
</ResponseField>

<ResponseField name="hits.entities" type="list[RecallEntity]">
  People, places, and things linked across observations.
</ResponseField>

<ResponseField name="confidence" type="float">
  Calibrated confidence in \[0, 1]. Higher means the returned memory is more likely to help.
</ResponseField>

<ResponseField name="timeline" type="str | None">
  A pre-rendered chronological summary of the relevant events. Set only when `include_timeline=True`.
</ResponseField>

<ResponseField name="mode" type="str">
  Echoes the request mode.
</ResponseField>

<ResponseField name="usage" type="Usage | None">
  `tokens_in` / `tokens_out` billed for this call. Always present in production.
</ResponseField>

### `RecallHit` fields (turns / observations)

```python theme={null}
@dataclass(frozen=True)
class RecallHit:
    id: str | None      # stable; persists across recalls
    text: str           # matched content
    score: float        # raw relevance, 0.0-1.0
    kind: str           # "turn" | "observation" | "entity"; defaults to "turn"
    timestamp: str | None
```

### `RecallEntity` fields (entities only)

```python theme={null}
@dataclass(frozen=True)
class RecallEntity:
    id: str | None
    label: str          # the entity label (e.g. "Acme")
    score: float
```

`RecallEntity` is **not** the same as `RecallHit`. It has `label` instead of `text`, and it does not have `kind` or `timestamp`.

## Examples

### Build a chatbot system prompt

```python theme={null}
def respond(user_msg: str, sid: str) -> str:
    hits = tex.recall(q=user_msg, session_id=sid, top_k=5)
    memory = "\n".join(f"- {h.text}" for h in hits.hits.turns)

    return llm.complete([
        {"role": "system", "content": f"Relevant memory:\n{memory}"},
        {"role": "user",   "content": user_msg},
    ])
```

### Confidence-gated fallback

```python theme={null}
hits = tex.recall(q=q, session_id=sid)

if hits.confidence < 0.3:
    hits = tex.recall(q=q, session_id=sid, mode="deep")

if hits.confidence < 0.2:
    return generate_without_memory(q)
```

### Temporal queries

```python theme={null}
hits = tex.recall(
    q="when did we discuss pricing?",
    session_id=sid,
    include_timeline=True,
)

if hits.timeline:
    print(hits.timeline)   # a pre-rendered chronological summary string
```

`timeline` is a free-form string. Drop it into a prompt as text. Do not treat it like an array.

### Multi-source recall

If you have both a long-lived user "bio" and a per-conversation session, query both:

```python theme={null}
bio = tex.recall(q=user_msg, session_id=f"bio-{user_id}", top_k=3)
chat = tex.recall(q=user_msg, session_id=f"chat-{conv_id}", top_k=5)

context = "\n".join(f"- {h.text}" for h in (bio.hits.turns + chat.hits.turns))
```

## Performance

| Mode     | Typical p50 | p99  | When to use                               |
| -------- | ----------- | ---- | ----------------------------------------- |
| `active` | 1.7s        | 2.5s | Every interactive call                    |
| `deep`   | 3.5s        | 6s   | Periodic analysis, low-confidence retries |

Set `timeout=2.0` on the constructor for interactive paths. Catch `APITimeoutError` and continue without memory:

```python theme={null}
try:
    hits = tex.recall(q=q, session_id=sid)
    context = format_context(hits)
except APITimeoutError:
    context = "(no memory available)"
return llm.complete(prompt_with(context))
```

<Card title="Next: Track usage" icon="receipt" href="/sdk/usage">
  Read your token totals.
</Card>