---
summary: "Every plugins.entries.active-memory key: type, meaning, range, and default, plus the extra tuning fields."
read_when:
  - You need the type or default for an active memory key
title: "Configuration reference"
---

## Configuration

All active memory configuration lives under `plugins.entries.active-memory`.

| Key                          | Type                                                                                                 | Meaning                                                                                                                                                                                                                                           |
| ---------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`                    | `boolean`                                                                                            | Enables the plugin itself                                                                                                                                                                                                                         |
| `config.mode`                | `"escalate" \| "always" \| "off"`                                                                    | Controls when the blocking deep-recall sub-agent runs; default `"escalate"`                                                                                                                                                                       |
| `config.agents`              | `string[]`                                                                                           | Agent ids that may use active memory                                                                                                                                                                                                              |
| `config.model`               | `string`                                                                                             | Optional blocking sub-agent model ref; when unset, inherits the current session model                                                                                                                                                             |
| `config.allowedChatTypes`    | `("direct" \| "group" \| "channel" \| "explicit")[]`                                                 | Session types that may run active memory; defaults to `["direct"]`                                                                                                                                                                                |
| `config.allowedChatIds`      | `string[]`                                                                                           | Optional per-conversation allowlist applied after `allowedChatTypes`; non-empty lists fail closed                                                                                                                                                 |
| `config.deniedChatIds`       | `string[]`                                                                                           | Optional per-conversation denylist that overrides allowed session types and allowed ids                                                                                                                                                           |
| `config.queryMode`           | `"message" \| "recent" \| "full"`                                                                    | Controls how much conversation the blocking sub-agent sees                                                                                                                                                                                        |
| `config.promptStyle`         | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Controls how eager or strict the blocking sub-agent is when deciding whether to return memory                                                                                                                                                     |
| `config.toolsAllow`          | `string[]`                                                                                           | Concrete memory tool names the blocking sub-agent may call; defaults to `["memory_search", "memory_get"]`, or `["memory_recall"]` when `plugins.slots.memory` is `memory-lancedb`; wildcards, `group:*` entries, and core agent tools are ignored |
| `config.thinking`            | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive" \| "max"`                | Advanced thinking override for the blocking sub-agent; default `off` for speed                                                                                                                                                                    |
| `config.fastMode`            | `boolean \| "auto"`                                                                                  | Optional fast-mode override for the blocking sub-agent; unset inherits normal agent, session, and model defaults                                                                                                                                  |
| `config.promptOverride`      | `string`                                                                                             | Advanced full prompt replacement; not recommended for normal use                                                                                                                                                                                  |
| `config.promptAppend`        | `string`                                                                                             | Advanced extra instructions appended to the default or overridden prompt                                                                                                                                                                          |
| `config.timeoutMs`           | `number`                                                                                             | Hard timeout for the blocking sub-agent (range 250-120000 ms; default 15000)                                                                                                                                                                      |
| `config.setupGraceTimeoutMs` | `number`                                                                                             | Advanced extra setup budget before the recall timeout expires; range 0-30000 ms, default 0. See [Cold-start grace](/concepts/active-memory/recommended-setup#cold-start-grace) for v2026.4.x upgrade guidance                                     |
| `config.maxSummaryChars`     | `number`                                                                                             | Maximum characters in the active-memory summary (range 40-1000; default 220)                                                                                                                                                                      |
| `config.logging`             | `boolean`                                                                                            | Emits active memory logs while tuning                                                                                                                                                                                                             |
| `config.persistTranscripts`  | `boolean`                                                                                            | Exports blocking sub-agent transcripts as JSONL artifacts before removing their temporary SQLite session rows                                                                                                                                     |
| `config.transcriptDir`       | `string`                                                                                             | Relative artifact directory under the plugin-owned per-agent transcript directory (default `"active-memory"`)                                                                                                                                     |
| `config.modelFallback`       | `string`                                                                                             | Optional model used only as the last step in the [model fallback chain](/concepts/active-memory/tuning#model-fallback-policy)                                                                                                                     |

Useful tuning fields:

| Key                                | Type     | Meaning                                                                                                                                                         |
| ---------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config.recentUserTurns`           | `number` | Prior user turns to include when `queryMode` is `recent` (range 0-4; default 2)                                                                                 |
| `config.recentAssistantTurns`      | `number` | Prior assistant turns to include when `queryMode` is `recent` (range 0-3; default 1)                                                                            |
| `config.recentUserChars`           | `number` | Max chars per recent user turn (range 40-1000; default 220)                                                                                                     |
| `config.recentAssistantChars`      | `number` | Max chars per recent assistant turn (range 40-1000; default 180)                                                                                                |
| `config.cacheTtlMs`                | `number` | Cache reuse for repeated identical queries (range 1000-120000 ms; default 15000)                                                                                |
| `config.circuitBreakerMaxTimeouts` | `number` | Skip recall after this many consecutive timeouts for the same agent/model. Resets on a successful recall or after the cooldown expires (range 1-20; default 3). |
| `config.circuitBreakerCooldownMs`  | `number` | How long to skip recall after the circuit breaker trips, in ms (range 5000-600000; default 60000).                                                              |