mirror of
https://github.com/n8n-io/n8n.git
synced 2026-06-01 09:17:08 +02:00
106 lines
3.7 KiB
Markdown
106 lines
3.7 KiB
Markdown
# 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 |
|