> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosage.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory system

> How conversation context, compaction, and durable memory are scoped and used.

AutoSage separates chat continuity from durable recall. Long conversations remain coherent through automatic compaction, while optional durable memory carries selected facts across separate conversations.

## Three kinds of context

| Context           | Purpose                                                       | Scope                                                  |
| ----------------- | ------------------------------------------------------------- | ------------------------------------------------------ |
| Recent history    | Keeps the latest turns verbatim, including tool-aware context | One chat                                               |
| Compacted history | Summarizes older turns when a chat becomes long               | One chat                                               |
| Durable memory    | Recalls relevant facts in future conversations                | Tenant, external subject, or restricted knowledge base |

<Info>
  Compaction does not depend on durable memory. A long chat can retain continuity even when durable memory is disabled or temporarily unavailable.
</Info>

## Durable-memory settings

Durable memory is opt-in at the tenant level:

| Setting     | Values                | Behavior                                                      |
| ----------- | --------------------- | ------------------------------------------------------------- |
| `mode`      | `disabled`, `durable` | Enables or disables cross-conversation memory                 |
| `retention` | `none`                | Recall may be configured, but new facts are not stored        |
| `retention` | `explicit_only`       | Store facts only when a user explicitly asks                  |
| `retention` | `automatic`           | Store useful facts automatically and accept explicit requests |

A knowledge base can narrow the tenant policy further with `kbMemoryMode`:

| KB mode         | Behavior                                                        |
| --------------- | --------------------------------------------------------------- |
| `disabled`      | Skip durable recall and storage for this knowledge base         |
| `subject`       | Use the caller's normal tenant or external-subject memory scope |
| `kb_restricted` | Use a separate memory scope isolated to this knowledge base     |

## Scope by caller

| Caller                                         | Durable-memory scope                   |
| ---------------------------------------------- | -------------------------------------- |
| Dashboard user                                 | Tenant-wide memory                     |
| API end user with `external_subject_id`        | Tenant plus that external subject      |
| API-key chat without `external_subject_id`     | Durable recall and storage are skipped |
| Any caller on a `kb_restricted` knowledge base | Separate scope for that knowledge base |

<Tip>
  Always pass the same stable `external_subject_id` for the same end user. This lets their memory persist across chats while keeping it isolated from every other end user served by the key.
</Tip>

See [Tenancy](/developers/concepts/tenancy) for the corresponding chat-ownership checks.

## Recall lifecycle

<Steps>
  <Step title="Prepare chat context">
    Long histories are compacted when needed. Recent turns remain verbatim and the older summary preserves decisions and prior context.
  </Step>

  <Step title="Resolve the memory scope">
    AutoSage applies the tenant policy, knowledge-base mode, caller type, and `external_subject_id` before any recall.
  </Step>

  <Step title="Recall relevant facts">
    Relevant durable memories are selected from the resolved scope and added as context for the current message.
  </Step>

  <Step title="Generate the answer">
    Memory context is combined with recent history, the new message, and any knowledge-base or tool results.
  </Step>

  <Step title="Retain new facts">
    When retention permits it, useful facts from the turn can be stored for future conversations.
  </Step>
</Steps>

Recall and storage are best-effort. They never block the grounded answer if memory is unavailable, and response metadata reports only a `memory_used` boolean rather than exposing recalled memory contents.

## Explicit memory

When durable memory is enabled and retention is `explicit_only` or `automatic`, users can store a fact directly with phrasing such as:

```
Remember this: I prefer quarterly reports as a PDF.
```

AutoSage confirms the memory operation instead of running a normal answer turn. Manage deletion through the memory management endpoints so changes are deliberate and scoped to the intended tenant or knowledge base.

## Management endpoints

| Method   | Path                                      | Purpose                                                        |
| -------- | ----------------------------------------- | -------------------------------------------------------------- |
| `GET`    | `/tenants/:id/memory-settings`            | Read tenant mode and retention                                 |
| `PATCH`  | `/tenants/:id/memory-settings`            | Update tenant mode or retention                                |
| `GET`    | `/tenants/:id/memories`                   | List or search tenant memories with `q`, `limit`, and `offset` |
| `DELETE` | `/tenants/:id/memories/:memoryId`         | Delete one tenant memory                                       |
| `GET`    | `/tenants/:id/memories/graph`             | Read the tenant entity graph                                   |
| `GET`    | `/knowledge-bases/:id/memories`           | List or search `kb_restricted` memories                        |
| `DELETE` | `/knowledge-bases/:id/memories/:memoryId` | Delete one restricted memory                                   |
| `GET`    | `/knowledge-bases/:id/memories/graph`     | Read the restricted entity graph                               |

Memory management requires the corresponding tenant or knowledge-base access. Restricted-KB endpoints return isolated data only when that knowledge base uses `kb_restricted` mode.

See the [Tenant API](/developers/api/tenants), [Knowledge-base API](/developers/api/knowledge-bases), and [Memory product docs](/memory/overview) for configuration and management details.

## Next steps

<CardGroup cols={2}>
  <Card title="Durable memory" icon="brain" href="/memory/durable-memory">
    Choose retention and knowledge-base memory modes.
  </Card>

  <Card title="Prompt assembly" icon="layer-group" href="/developers/concepts/prompt-assembly">
    See where memory and compacted history enter a run.
  </Card>
</CardGroup>