# Memory System

## Overview

The memory system serves three purposes:

- **Native agent persistence** — thread and message storage through the
  `@n8n/agents` `BuiltMemory` interface.
- **Operational context management** — rolling compaction of older messages into
  a thread metadata summary when the conversation approaches the model context
  window.
- **Conversation continuity** — recent messages, optional semantic recall, plan
  state, retry history, checkpoints, and UI run snapshots for the current
  thread.

Sub-agents are stateless. Context is passed through the briefing, and retry
history is appended from thread-scoped iteration logs.

## Tiers

### Tier 1: Native Storage

Instance AI uses n8n's application database for native agent storage.

| Store | Tables |
|-------|--------|
| `TypeORMAgentMemory` | `instance_ai_threads`, `instance_ai_messages`, `instance_ai_resources` |
| `TypeORMAgentCheckpointStore` | `instance_ai_checkpoints` |
| UI run snapshots | `instance_ai_run_snapshots` |
| Iteration logs | `instance_ai_iteration_logs` |
| Temporary workflow mapping | `ai_builder_temporary_workflow` |

The obsolete workflow snapshot and observational memory tables are dropped by
the native agents reset migration. Existing Instance AI runtime data may be
cleared during that migration.

### Tier 2: Recent Messages

A sliding window of the most recent N messages is sent as context to the LLM on
every request.

- **Default**: 20 messages
- **Config**: `N8N_INSTANCE_AI_LAST_MESSAGES`

### Tier 3: Rolling Compaction

`InstanceAiCompactionService` estimates thread token usage. When a conversation
exceeds the configured context threshold, older messages outside the recent
tail are summarized by a native compaction agent.

Compaction state is stored in thread metadata under
`instanceAiConversationSummary`. Raw messages remain in the database for UI and
debugging; compaction only changes the model input.

### Tier 4: Semantic Recall (Optional)

When configured and supported by the active memory backend, the native agents
runtime can retrieve semantically related past messages and inject them into
context.

- **Config**: `N8N_INSTANCE_AI_EMBEDDER_MODEL`
- **Config**: `N8N_INSTANCE_AI_SEMANTIC_RECALL_TOP_K` (default: 5)

Disabled by default.

### Tier 5: Plan And Retry State

The `plan` tool stores execution plans in thread metadata. Workflow loop
attempts are stored in `instance_ai_iteration_logs` and appended to sub-agent
briefings on retry.

### Tier 6: Checkpoints And Run Snapshots

Native checkpoints persist suspended agent state for human-in-the-loop resume.
Run snapshots persist the UI agent tree used to reconstruct visible progress
after reconnects.

## Scoping Model

All memory is thread-scoped unless a native memory call explicitly requests a
resource-scoped working-memory key.

- **Recent messages** — current conversation history.
- **Compaction summary** — older context summarized for the same thread.
- **Plan and iteration logs** — current task state and retry history.
- **Checkpoints** — suspended native agent state keyed by run.

### Sub-Agent Memory

Sub-agents do not read or write persistent memory directly. The orchestrator
builds their briefing from the current request, relevant task state, and retry
history.

### Cross-User Isolation

Each user's memory is independent. The agent cannot see other users'
conversations or semantic history.

## Configuration

| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `N8N_INSTANCE_AI_LAST_MESSAGES` | number | 20 | Recent message window |
| `N8N_INSTANCE_AI_EMBEDDER_MODEL` | string | `''` | Embedder model for semantic recall (empty = disabled) |
| `N8N_INSTANCE_AI_SEMANTIC_RECALL_TOP_K` | number | 5 | Number of semantic matches |