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.
• 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.