Advanced Memory Configuration

+15 Mana ✨
OpenClaw Configuration Documentation(DOCUMENTATION)

Introduction

Beyond the default memory behaviour, OpenClaw offers extensive configuration for embedding providers, caching, session resets, and automatic memory management. Mastering these settings lets you optimise for cost, latency, privacy, and context quality. This lesson covers embedding providers, the SQLite cache, auto flush, and session reset mechanics.

Key Concepts

  • Embedding Providers — pluggable services (OpenAI, Gemini, Voyage for remote; node-llama-cpp GGUF for local) that convert text into vector representations for semantic search.
  • Embedding Cache — a SQLite database that stores computed embeddings to avoid redundant API calls, defaulting to 50,000 entries.
  • Auto Memory Flush — a silent agentic turn that runs before compaction to persist important context from the session into memory files.
  • Session Reset — configurable rules that clear session context: daily at 4:00 AM by default, with idle-based and per-type overrides available.
  • Context Compaction — the process of trimming old tool results before LLM calls to keep the context window manageable.

Real World Context

A company running OpenClaw agents on sensitive internal data might require all embeddings to stay on-premise. By configuring node-llama-cpp with a local GGUF model, they avoid sending any text to external APIs. Meanwhile, the embedding cache ensures that repeatedly referenced documents do not incur redundant computation costs, and session reset rules ensure stale context does not accumulate overnight.

Deep Dive

Embedding Providers

OpenClaw supports multiple embedding providers through a pluggable architecture:

yaml
# Remote providers
embeddingProvider: openai      # OpenAI embeddings API
embeddingProvider: gemini      # Google Gemini embeddings
embeddingProvider: voyage      # Voyage AI embeddings

# Local provider
embeddingProvider: node-llama-cpp  # Local GGUF model, fully offline

Before choosing a provider, consider the trade-offs. Remote providers (OpenAI, Gemini, Voyage) offer high-quality embeddings with minimal setup but require sending text to external services. The local provider (node-llama-cpp with GGUF models) keeps everything on-device, trading some quality and speed for complete privacy.

If no provider is explicitly configured, OpenClaw uses auto-selection, picking the best available provider based on what API keys and local models are present.

Embedding Cache

To avoid recomputing embeddings for the same text, OpenClaw maintains a SQLite-backed cache:

yaml
embeddingCache:
  maxEntries: 50000    # Default capacity
  backend: sqlite      # Storage backend

The cache stores text-to-embedding mappings so that repeated searches over the same memory files do not trigger new API calls. With a default capacity of 50,000 entries, most agents can cache months of daily logs without eviction.

After the cache fills to capacity, the oldest entries are evicted using an LRU (Least Recently Used) policy. This means frequently accessed embeddings stay cached while stale ones are recalculated on demand.

Session Reset Rules

Sessions reset automatically to prevent unbounded context growth:

yaml
sessionReset:
  daily: "04:00"           # Reset at 4:00 AM (default)
  idleMinutes: 120         # Reset after 2 hours of inactivity
  perType:
    group: "02:00"         # Group sessions reset at 2:00 AM
  perChannel:
    slack-general: 60      # Slack #general resets after 60 min idle

Before a reset fires, understand what it does: it clears the active session context, effectively starting a fresh conversation. The daily reset at 4:00 AM is a sensible default for most agents — it ensures each day begins with a clean slate.

The idleMinutes setting adds inactivity-based resets. If no messages arrive for the configured duration, the session resets automatically. Per-type and per-channel overrides allow fine-grained control: group chats might reset more frequently than private sessions, and high-traffic channels might need shorter idle timeouts.

Auto Memory Flush

Before context compaction occurs, OpenClaw runs a silent agentic turn to flush important information from the session into memory files:

text
Session Context Getting Large
  ↓
Auto Memory Flush (silent agentic turn)
  ↓ Persists key facts to daily log / MEMORY.md
Context Compaction
  ↓ Trims old tool results
Continue Session with Trimmed Context

This flush is invisible to the user — no message is displayed, and no response is generated. The agent silently examines the session, identifies important information that might be lost during compaction, and writes it to the appropriate memory file.

After the flush completes, context compaction trims old tool results and verbose outputs, keeping the context window within the LLM's limits. The combination ensures that no critical information is lost when the context is trimmed.

Session Commands

Users can manually manage sessions through built-in commands:

text
/new          — Start a new session
/reset        — Reset the current session
/status       — Show session status and metadata
/context list — List loaded context items
/context detail — Show detailed context breakdown
/stop         — Stop the current agent
/compact      — Manually trigger compaction
/send on|off  — Toggle message sending

These commands provide direct control over the session lifecycle, complementing the automatic reset and compaction mechanisms.

Common Pitfalls

  • Choosing a remote embedding provider for sensitive data — if your agent handles confidential information, use the local node-llama-cpp provider to keep all text on-device.
  • Setting idle reset too aggressively — a very short idleMinutes value causes frequent context resets, which can frustrate users who pause mid-conversation. Start with 120 minutes and adjust based on usage patterns.
  • Ignoring the embedding cache size — if your agent processes a very high volume of unique content, the default 50,000 entries may fill quickly. Monitor cache eviction rates and increase the limit if needed.

Best Practices

  • Use auto-selection for embedding providers unless you have a specific reason to pin a provider. Auto-selection adapts to the available environment.
  • Configure per-channel reset rules for channels with different usage patterns — high-traffic channels benefit from shorter idle timeouts, while low-traffic channels can use longer ones.
  • Trust the auto memory flush — it runs silently before compaction to preserve important context. Avoid manually duplicating this work by writing to memory files before every compaction.

Summary

  • OpenClaw supports four embedding providers: OpenAI, Gemini, and Voyage (remote) plus node-llama-cpp GGUF (local), with auto-selection as the default.
  • The SQLite embedding cache stores up to 50,000 entries by default, using LRU eviction.
  • Sessions reset daily at 4:00 AM by default, with configurable idle-based, per-type, and per-channel overrides.
  • Auto memory flush runs a silent agentic turn before compaction to persist important context to memory files.
  • Manual session commands (/new, /reset, /status, /compact, etc.) give users direct control over the session lifecycle.
✓ Completed