# AI Memory

Agent memory gives an agent context that persists beyond a single message. It is configured under an agent's `memory` block and is composed of **three independent tiers**, each disabled by default and enabled individually. Before the runtime invokes the LLM (for example, when the `ai:agent` automation action dispatches a task), it assembles context from whichever tiers are enabled.

| Tier           | Persistence                         | Direction  | Purpose                                               |
| -------------- | ----------------------------------- | ---------- | ----------------------------------------------------- |
| `conversation` | Session-level (ephemeral, windowed) | Read       | Maintain dialogue context across recent messages.     |
| `knowledge`    | Read-only RAG sources               | Read       | Retrieve relevant documents via semantic search.      |
| `facts`        | Persistent across sessions          | Read/write | Remember AI-managed facts the agent learns over time. |

```yaml
agents:
  - name: support-agent
    role: support
    systemPrompt: Be helpful and remember the customer's preferences.
    memory:
      conversation:
        enabled: true
        windowSize: 10
        summarize: true
      knowledge:
        enabled: true
        sources: [faq, docs]
        retrievalLimit: 5
        similarityThreshold: 0.7
      facts:
        enabled: true
        maxFacts: 100
        namespace: support
```

## Conversation Memory

Retains recent messages from the agent's session. When enabled, the runtime loads the last `windowSize` messages into context before each invocation.

| Property     | Default | Description                                                                   |
| ------------ | ------- | ----------------------------------------------------------------------------- |
| `enabled`    | `false` | Whether conversation memory is active.                                        |
| `windowSize` | `10`    | Number of recent messages kept in context.                                    |
| `summarize`  | `false` | When `true`, older messages are compressed into a summary instead of dropped. |

## Knowledge Memory

RAG-based semantic retrieval from configured knowledge sources. When enabled, the runtime runs a similarity search against the listed sources before each invocation and injects the most relevant documents into context. This is the _runtime retrieval_ side of RAG — distinct from the agent's `knowledge` block, which defines the _input sources_ that get embedded.

| Property              | Default | Description                                                                   |
| --------------------- | ------- | ----------------------------------------------------------------------------- |
| `enabled`             | `false` | Whether knowledge retrieval is active.                                        |
| `sources`             | —       | Knowledge source names to search (must reference configured knowledge bases). |
| `retrievalLimit`      | `5`     | Maximum documents retrieved per query.                                        |
| `similarityThreshold` | `0.7`   | Minimum similarity score (`0`–`1`) for a retrieved document to be included.   |

:::callout
**Knowledge memory reuses the RAG pipeline.** Retrieval runs against the same vector store described in [AI RAG](/en/docs/ai-rag) — pgvector on PostgreSQL or `Float32` BLOB + app-side cosine on SQLite.
:::

## Facts Memory

Persistent key-value facts the agent learns across sessions. Unlike the `state` automation action (explicit developer-set KV), facts are **AI-managed**: the agent itself decides what is worth remembering. Facts are retrieved by semantic relevance to the current task, not by exact-key lookup.

| Property    | Default    | Description                                                                         |
| ----------- | ---------- | ----------------------------------------------------------------------------------- |
| `enabled`   | `false`    | Whether facts memory is active.                                                     |
| `maxFacts`  | `100`      | Maximum number of facts the agent can store.                                        |
| `namespace` | agent name | Namespace for fact isolation. Lowercase, starts with a letter (`^[a-z][a-z0-9-]*`). |

### Namespace Isolation & Per-User Scoping

Facts are partitioned by `namespace` (defaulting to the agent's name), so two agents never read each other's learned facts. Combined with the agent-as-user model — each agent is a distinct `auth.user` — this gives per-agent and, where chat scopes by session, per-user fact isolation. An agent cannot leak one customer's learned facts into another customer's conversation.

## Tier Composition

All three tiers are optional and combine freely. A read-only analyst agent might enable only `knowledge`; a long-running support agent might enable all three. When multiple tiers are enabled, the runtime assembles context from each before invoking the LLM:

```
conversation (recent dialogue)
        +
knowledge (semantically-retrieved docs)
        +
facts (relevant learned facts)
        ▼
   assembled context → LLM
```

## Related Pages

- [AI Agents](/en/docs/ai-agents) — the agent the `memory` block belongs to.
- [AI RAG](/en/docs/ai-rag) — the embedding/retrieval pipeline knowledge memory uses.
- [AI Chat](/en/docs/ai-chat) — conversation history in the chat interface.
- [AI Overview](/en/docs/ai-overview) — the full AI ecosystem.