OpenClaw Memory Management Explorer

01Architecture Overview

OpenClaw uses a two-layer memory design. MEMORY.md serves as a curated, always-loaded bootstrap file injected into the system prompt. Daily logs in memory/YYYY-MM-DD.md capture session-specific memories that persist across context compactions. Both layers are indexed into a SQLite database for fast hybrid search.

A file watcher monitors the workspace for changes and keeps the SQLite index in sync. When the agent needs to recall past context, it uses memory_search to query the index and memory_get to retrieve specific lines from memory files.

02Memory Tools

Two tools provide read access to the memory system. Both are defined in src/agents/tools/memory-tool.ts.

memory_search

Performs hybrid vector + keyword search across all indexed memory files.

Return structure per result:

{
  path:     "memory/2026-02-24.md",   // relative file path
  startLine: 12,                       // chunk start line
  endLine:   28,                       // chunk end line
  score:     0.72,                     // combined similarity score
  snippet:   "...",                    // matched text excerpt
  citation:  "memory/2026-02-24.md#L12-L28"
}

memory_get

Retrieves raw text content from a specific memory file. Used after memory_search to pull the full context around a matched snippet.

Access control: Both tools only access .md files within the workspace MEMORY.md and memory/ directory. Files outside this scope are rejected.

03Storage Format

Memory data lives in two forms: human-readable Markdown files on disk and a SQLite database that indexes them for fast search.

File Layout

~/.openclaw/workspace/
  MEMORY.md                  # Curated bootstrap (always in system prompt)
  memory/
    2026-02-11.md            # Daily session logs
    2026-02-14.md
    2026-02-17.md
    ...

~/.openclaw/memory/
  {agentId}.sqlite           # SQLite index database

SQLite Database

The database at ~/.openclaw/memory/{agentId}.sqlite contains six tables. Schema defined in src/memory/memory-schema.ts.

04Search Pipeline

When memory_search is called, the query passes through a 9-step hybrid search pipeline. Implementation spread across src/memory/hybrid.ts, src/memory/mmr.ts, and src/memory/temporal-decay.ts.

Embedding Providers

The embedding step supports multiple providers. Configured via agents.defaults.memorySearch.provider.

05Memory Lifecycle

From the moment an agent writes a memory file to the moment that content appears in search results, the data passes through a multi-stage pipeline.

06Memory Flush

When a session approaches the context window limit, OpenClaw triggers a silent "memory flush" turn before compaction. This ensures important context is written to disk before the conversation history is truncated.

Trigger Condition

totalTokens ≥ contextWindow − reserveTokensFloor − softThresholdTokens

Where softThresholdTokens defaults to 4000. When the total token count crosses this threshold, a flush is initiated.

Flush Process

07System Prompt Integration

Memory is woven into the system prompt at three points. These only appear in full prompt mode.

Citation Modes

When memory_search returns results, citations can be included automatically. Configured via memory.citations.

08Configuration

The full memory system is controlled by configuration paths under agents.defaults.memorySearch and related namespaces. Defined in src/config/types.tools.ts.

09Real-World Example

A real OpenClaw workspace's memory footprint, showing how the layers work in practice.

MEMORY.md

The curated bootstrap file — 237 lines covering identity, preferences, workflows, and lessons learned. Always loaded into the system prompt.

# OpenClaw Memory

## Identity & Role
- Agent name: Claw
- Primary operator: jingtao
- Running on: ailearn (Azure VM, Ubuntu 24.04)

## Preferences & Conventions
- Language: All code, comments, docs in English
- Git: Imperative mood commits, PRs via gh CLI
- Docker: V2 plugin syntax (docker compose)

## Workflows
- Server provisioning via numbered scripts (00-, 01-, 02-...)
- Docker services at vm/docker-services/<category>/<name>/
- Projects at projects/<name>/ with Dockerfile + docker-compose.yml

## Lessons Learned
- Always check CLAUDE.md conventions before modifying ai-learn repo
- Use set -euo pipefail in all bash scripts
- nginx-proxy needs VIRTUAL_HOST + LETSENCRYPT_HOST for HTTPS
...

Daily Logs

Seven daily log files spanning 2026-02-11 to 2026-02-24, capturing session-specific memories written during memory flushes.

memory/
  2026-02-11.md    # Initial setup session
  2026-02-14.md    # Docker service configurations
  2026-02-17.md    # OpenClaw Explorer project creation
  2026-02-19.md    # System prompt page development
  2026-02-20.md    # Skill system exploration
  2026-02-22.md    # Multi-page restructuring
  2026-02-24.md    # Memory management research

SQLite Index

The database file main.sqlite (68 KB) indexes all memory files into searchable chunks with embeddings.