Agent Memory & Context

Common Pain Points

Agent forgets its name/personality after restart
Built-in memory returns empty results
Identity .md files not loaded on session start
Agent thinks it's a different time (cached timestamps)

OpenClaw agents use a combination of system prompts, identity files, and built-in memory to maintain context. This guide explains how each works and how to fix common memory-related issues.

Jump to Section

Quick Fix: Identity Lost Why Agents Forget Memory Chunking Fix Empty Memory Results Identity Files Cached Timestamps Diagnostic Commands

Quick Fix: Agent Lost Its Identity

If your agent forgot its name or personality after a restart:

Set system prompt path to your identity file

# Point the agent to your identity/personality file
openclaw config set agents.defaults.systemPromptPath ~/.openclaw/agents/main/agent/identity.md
openclaw gateway restart

Create an identity file if you don't have one

# Create a simple identity file
mkdir -p ~/.openclaw/agents/main/agent
cat > ~/.openclaw/agents/main/agent/identity.md << 'EOF'
# Agent Identity

You are [Agent Name], a helpful AI assistant.

## Personality
- Friendly and professional
- Concise responses
- Always verify before acting

## Rules
- Never share API keys
- Always confirm destructive actions
EOF

Why Agents Forget After Restart

When a session ends or the gateway restarts, the conversation context is lost. The agent starts fresh with only the system prompt. If your personality/identity was established through conversation (not a file), it disappears.

System prompt loaded

At session start, only the system prompt file (if configured) is injected into context.

No automatic memory recall

The built-in memory tool exists but is NOT automatically queried at session start.

Identity file must be configured

Your .md personality file is only loaded if systemPromptPath points to it.

Conversation context is ephemeral

Everything said in the previous session is gone unless stored in memory.

Memory Chunking: How It Works

The built-in memory tool stores and retrieves information using vector similarity search. Text is split into chunks, embedded, and stored. When you search, the query is compared against all chunks.

Section-Aware Splitting

Splitting on ## heading boundaries (instead of fixed character counts) reduces the memory miss rate from 58% to 17%. This keeps related information together within the same chunk.

Best practice: Structure your memory-worthy documents with ## headings. Each section should be self-contained (100-500 words) to optimize retrieval accuracy.

Fix: Built-in Memory Returns Empty

If memory_search returns nothing even though you've stored information:

Check memory files exist

Memory files are stored in ~/.openclaw/agents/main/agent/memory/. If the directory is empty, nothing was stored.

Structured markdown causes short chunks

Documents with many ## headings create very small chunks that fall below the relevance threshold. Consolidate small sections.

Reindex after manual edits

If you manually edited memory files, the index is stale. Run openclaw memory reindex to rebuild.

Check and rebuild memory

# Check if memory files exist
ls ~/.openclaw/agents/main/agent/memory/

# Rebuild the memory index
openclaw memory reindex

# Restart to pick up changes
openclaw gateway restart

Identity Files (.md)

Identity files define your agent's personality, rules, and knowledge. They are loaded as the system prompt at session start — but only if configured.

Check current system prompt path

openclaw config get agents.defaults.systemPromptPath

Common Mistake

Creating an identity.md file in the agent directory does NOT automatically load it. You must explicitly set systemPromptPath to point to it.

Cached Timestamps (Time-Frozen Perception)

Some agents report the wrong date/time because cached session state includes a timestamp from a previous session. The agent literally thinks it's still yesterday.

Clear cached session state

# Delete cached state that may contain stale timestamps
rm -f ~/.openclaw/agents/main/agent/state.json
rm -rf ~/.openclaw/agents/main/agent/cache/
openclaw gateway restart

Diagnostic Commands

Full memory diagnostic

# Check agent directory structure
ls -la ~/.openclaw/agents/main/agent/

# Check memory files
ls -la ~/.openclaw/agents/main/agent/memory/

# Check system prompt configuration
openclaw config get agents.defaults.systemPromptPath

# Check if identity file exists
cat ~/.openclaw/agents/main/agent/identity.md

# Rebuild memory index
openclaw memory reindex

Related Guides

Context and memory optimization: