> ## 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.

# How memory works

> What Tex stores after remember, and how soon each layer can appear in recall.

export const PipelineFlow = ({steps, caption}) => <div className="not-prose my-6">
    <figure className="rounded-xl border border-zinc-950/15 bg-zinc-950/[0.02] p-4 dark:border-white/15 dark:bg-white/[0.04]">
      {caption && <figcaption className="mb-3 text-sm font-semibold text-zinc-900 dark:text-zinc-100">
          {caption}
        </figcaption>}
      <div className="mx-auto flex max-w-xl flex-col" role="list">
        {steps.map((step, i) => <div key={step.id} className="flex flex-col items-stretch">
            <div className="flex w-full flex-col rounded-lg border border-[#F32C05]/40 bg-[#F32C05]/10 p-3 dark:border-[#FF5530]/45 dark:bg-[#F32C05]/15" role="listitem" aria-label={`${step.id}: ${step.label}`}>
              {step.phase && <div className="text-[10px] font-semibold uppercase tracking-wide text-zinc-600 opacity-80 dark:text-zinc-400">
                  {step.phase}
                </div>}
              <div className="mt-1.5 text-sm font-semibold text-zinc-900 dark:text-zinc-50">{step.label}</div>
              {step.hint && <div className="mt-2 text-xs leading-snug text-zinc-600 dark:text-zinc-400">{step.hint}</div>}
            </div>
            {i < steps.length - 1 && <div className="flex h-8 shrink-0 items-center justify-center text-sm font-medium text-zinc-400 dark:text-zinc-500" aria-hidden>
                ↓
              </div>}
          </div>)}
      </div>
    </figure>
  </div>;

Call **`remember`** when you have new turns to store. Call **`recall`** when you have a question and want the best matches back.

Most of the time you work with **turns**. Tex also builds **observations** and **entities** in the background. A write usually becomes recallable in about **150 ms**. The richer memory layers continue after that.

## Layers

<CardGroup cols={3}>
  <Card title="Turns" icon="comments">
    Raw lines: who said what, when.
  </Card>

  <Card title="Observations" icon="lightbulb">
    Small facts inferred from turns, such as dietary constraints or locations.
  </Card>

  <Card title="Entities" icon="diagram-project">
    People, places, and organizations that show up across observations.
  </Card>
</CardGroup>

## Writes

When you call **`remember`**, Tex first saves the turn in active memory. That is the fast path. Then it keeps building richer memory in the background.

<PipelineFlow
  caption="Write path"
  steps={[
{
  id: "remember",
  label: "remember",
  phase: "Request",
  hint: "You send turns + scope.",
},
{
  id: "active",
  label: "Active memory",
  phase: "~150 ms",
  hint: "Recall can find this soon after the write.",
},
{
  id: "return",
  label: "Your code resumes",
  phase: "Response",
  hint: "Your app can keep going.",
},
{
  id: "enrich",
  label: "Passive enrichment",
  phase: "Async",
  hint: "Observations, entities, and timeline work.",
},
]}
/>

### Fast path

Your code gets control back quickly. New turns are usually recallable within about **150 ms**.

### Background

Observations, entities, and timeline work continue after the response. They improve recall on later questions.

You do not need the background work to finish before the next user message. The latest turn can still be enough.

## Reads

For reads, pass a natural-language **`q`** and the scope to search. Tex retrieves candidates, ranks them, and returns **`hits`** with a **`confidence`** score.

Over HTTP, **`POST /recall`** takes **`q`**, **`scope`**, and options like **`mode`**, **`top_k`**, and **`include_timeline`**. The response includes ranked turns, observations, entities, token **`usage`**, and an optional **`timeline`** string. The full request and response fields are in [Recall memory](/api-reference/memory/recall).

<PipelineFlow
  caption="Read path"
  steps={[
{ id: "q", label: "Your query", phase: "Input", hint: "Natural language + scope." },
{ id: "expand", label: "Expansion", phase: "Retrieval", hint: "Tex expands the query." },
{ id: "hybrid", label: "Hybrid retrieval", phase: "Index", hint: "Vectors, time, and entity graph." },
{ id: "rerank", label: "Cross-encoder rerank", phase: "Rank", hint: "Scores each candidate." },
{ id: "conf", label: "Calibrated confidence", phase: "Output", hint: "Use this to decide whether memory is strong enough." },
{ id: "hits", label: "Top-k hits", phase: "Payload", hint: "Turns, observations, and entities." },
]}
/>

Tune **`mode`**, **`top_k`**, and **`confidence`** behavior in [Recall and ranking](/concepts/retrieval).

## One example turn

```python theme={null}
{"role": "user", "text": "I just moved from Seattle to Austin for a job at Acme.", "timestamp": "..."}
```

| Layer        | What you get                                     |
| ------------ | ------------------------------------------------ |
| Turn         | Full text, role, timestamp, dedupe metadata      |
| Observations | Facts like current city, previous city, employer |
| Entities     | Typed nodes (person, place, org) wired together  |
| Temporal     | Events on a lightweight timeline                 |

## BYO facts

Let Tex extract facts for you. If you already have facts from your own system, attach them to **`remember`**. See [`conversations.remember`](/sdk/conversations-remember).

<Card title="Next: scopes and multi-tenancy" icon="layer-group" href="/concepts/scopes" horizontal>
  How `org_id`, `user_id`, and `session_id` isolate memory.
</Card>