# Memory and Context

This guide explains how the agent remembers information, how it manages conversation history, and how you can control what it learns and retains.

## How the Agent Remembers

The agent uses a multi-tiered memory system to provide relevant context while staying within the limits of its AI model.

### 1. Short-Term Memory (The Current Conversation)
The agent keeps track of your current session's back-and-forth messages. However, as the conversation grows very long, it may exceed the "context window" (the maximum amount of text the AI can process at once).

### 2. Context Pruning and Summarization
To save tokens and stay within limits, the agent automatically "prunes" old messages when the conversation gets too long:
- **Summarization**: The agent uses an AI model to create a concise summary of the older parts of the conversation.
- **Archiving**: The full transcript of the pruned messages is saved to an archive, which the agent can still search if needed.
- **Retention**: The agent always keeps the most recent messages and the summary of previous interactions in its active memory.
- **When the summary fails**: the summary is asked of the background model (the Gemini model of `ai.gemini` where it has a key, else the agent's own model), retried when the provider is briefly overloaded and then asked of the agent's fallback models (`ai.fallback`, or the agent's own `fallback` list). If every one fails, the older messages stay in the conversation and the next turn tries again; they are archived and trimmed without a summary only once the conversation is twice past its limit, or when no model is configured at all.

### 3. Long-Term Memory (RAG)
For information that needs to last across different sessions, the agent uses **Retrieval-Augmented Generation (RAG)**. It stores facts and notes in two ways:
- **Global Memory**: General knowledge or organizational facts that apply to everyone.
- **Personal Memory**: Facts specifically about you (preferences, role, specific tasks).

All long-term memories are stored in GoClaw's state database (**SQLite** by default) for high-performance searching and strict privacy isolation.

The agent uses **Hybrid Search** (combining keyword search and, when `memory.search.provider` is set, AI-powered semantic search) to find the most relevant information from its database and archive files when you ask a question.

## Background Learning (Asynchronous)

GoClaw learns from your interactions without slowing down the conversation:
- **Fact Extraction**: After a session is summarized, a background process automatically identifies and saves new facts about your environment or preferences.
- **Auto-Correction**: If a tool fails (e.g., a wrong database table name), the error comes back with a hint and the matching approved saved queries or tool presets, so the agent corrects the call in the same turn. Nothing is stored from the failure; to make the right approach permanent, an admin saves it as a [saved query or tool preset](saved-queries.md).
- **Job Queue**: These tasks are queued and processed sequentially, ensuring the agent remains responsive and the database stays stable.

## Memory Consolidation

Over time, global memory and daily notes can become cluttered. An administrator (or the agent, in an admin or system run) can run the `memory_consolidate` tool, which:
1. Collects global memory records and daily memory files (`memory/YYYY-MM-DD.md`) older than `memory.consolidate_after_days` (30 by default; the tool's `lookback_days` argument overrides it).
2. Extracts the most important facts using AI.
3. Moves these facts into a long-term "Core Memory" file (`Memory.md`) which serves as the agent's primary bootstrap context.
4. Deletes the processed records and moves the processed files to `memory/archived/`.

`dry_run: true` reports what would be consolidated without changing anything.

Separately, a built-in daily job (`sys-memory-consolidate`, 03:00) merges learned agent notes that say the same thing into one record. Each merge is recorded, and an administrator can undo it with `goclaw memory revisions undo`.

## User-Facing Configuration

You can influence how the agent uses memory through configuration (usually in `config.yaml`):

| Setting | Default | Description |
|---------|---------|-------------|
| `memory.search.provider` | empty | Embedding provider for semantic search: `gemini`, `openai` or `ollama`, using that provider's key or address from `ai:`. Empty means keyword search only. |
| `memory.search.model` | the provider's default | Embedding model. |
| `memory.session_memory.max_tokens` | `40000` | When a conversation grows past this many tokens, its older messages are summarized and trimmed, to 60% of the limit, so that the next turns leave its start unchanged and the provider can read it from its prompt cache. A digit or a non-Latin (for example Cyrillic) letter counts as one token, other text as four characters a token, about as the model counts them. A conversation keeps at most half of `memory.auto_flush_tokens`, whatever this says: more would put every turn past the flush threshold at its first call. To keep more history, raise both. |
| `memory.session_memory.messages` | `40` | Messages to keep instead, used only when `max_tokens` is `0`; past it, the conversation is trimmed to 60% of it. |
| `memory.session_memory.enabled` | `true` | `false` keeps the transcript of a session cleared with `/new` or `/reset` out of memory. |
| `memory.bootstrap_max_chars` | `20000` | Most characters of `Memory.md` put into each prompt; a longer file keeps its beginning and end. An agent's own `bootstrap_max_chars` in `agents.list` overrides it. |
| `memory.auto_flush_tokens` | `80000` | When one request's messages grow past this many tokens, the older ones are distilled into the daily memory file and dropped from the request. `memory.flush.threshold_tokens` sets the same thing when this is left at its default; `memory.flush.enabled: false` turns the flush off. |
| `memory.context_budget_chars` | `32000` | Most characters of memory, notes and lessons put into each prompt; the lowest-priority sections are dropped first. `0` means no limit. |
| `memory.consolidate_after_days` | `30` | Age after which `memory_consolidate` takes records and daily files. |
| `memory.write_access` | `enabled: true`, `allowed_roles: ["system"]` | Who may write global memory: administrators, callers whose role is in `allowed_roles` (`system` is the Web UI administrator) and the users in `allowed_users`. With `enabled: false`, only administrators may. SOP, cron and webhook runs never write global memory. |

`memory.mode` and `memory.search.enabled` are accepted but not read: memory is saved the same way whatever `mode` says, and search is semantic when `memory.search.provider` is set and keyword-only otherwise.

## Privacy and Isolation

The agent respects your privacy through **Memory Isolation**:
- Your **Personal Memory** is only accessible to you and administrators.
- When the agent searches for information, it filters out personal files belonging to other users.
- Each platform (Discord, MS Teams, Facebook, Telegram, the App API, Web) uses a unified identity to ensure your preferences follow you across channels.

## Core Instructions

Administrators can set **Core Instructions** for the agent. These are persistent rules that survive session resets and define the agent's fundamental behavior, persona, and boundaries. Unlike regular memory, these cannot be overridden by standard users during a conversation.