Core Concepts12 min readIntermediate

Persistent Memory

How OpenClaw remembers you and becomes uniquely yours. Your preferences, your context, your AI memory management

What You'll Learn

  • How OpenClaw persists and stores conversation history
  • Session lifecycle and reset policies
  • Configure memory retention and cleanup rules
  • Share conversation context across devices
  • Use CLI tools to manage and inspect sessions

Table of Contents

Core Concept

OpenClaw treats one direct-chat session per agent as primary. Direct chats collapse to agent:\<agentId\>:\<mainKey\> (default main), while group/channel chats get their own independent keys. This ensures your AI assistant remembers you across all devices.

💡 Gateway is the single source of truth — all session state is owned by the gateway, UI clients (macOS app, WebChat, etc.) must query the gateway for session lists and token counts.

Single Source of Truth

Gateway owns all session state, UI clients fetch data from gateway instead of reading local files

Persistent Storage

Sessions stored in ~/.openclaw/agents/\<agentId\>/sessions/sessions.json, conversation history saved as JSONL files

Automatic Management

Sessions automatically expire and cleanup based on configured reset policies, supporting daily reset and idle timeout

Flexible Configuration

Control session scope, reset policies, and identity links through configuration files

Where State Lives

On the gateway host, OpenClaw stores session data in the following locations:

~/.openclaw/agents/\<agentId\>/sessions/sessions.json

Session store: Per-agent session map containing session ID, updated time, and other metadata

~/.openclaw/agents/\<agentId\>/sessions/\<SessionId\>.jsonl

Transcripts: Complete conversation history for each session, stored in JSONL format

Remote Mode Tip

In remote mode, the session store you care about lives on the remote gateway host, not your Mac. Make sure to inspect and manage sessions on the correct machine.

Session Lifecycle

🎯

Creation

New session created when first message received, or forced with /new, /reset commands

💬

Active Use

Session updated on each message, maintaining conversation context and relevant memories

⏰

Reset Evaluation

Each message evaluates whether session has expired (based on daily reset time or idle time)

🔄

Expiration & Reset

Expired sessions marked as stale, next message creates new session ID

Configuration Options

You can configure session behavior through ~/.openclaw/openclaw.json. Here's an example configuration:

{
  "session": {
    "scope": "per-sender",
    "dmScope": "main",
    "identityLinks": {
      "alice": ["telegram:123456789", "discord:987654321012345678"]
    },
    "reset": {
      "mode": "daily",
      "atHour": 4,
      "idleMinutes": 120
    },
    "resetByType": {
      "thread": { "mode": "daily", "atHour": 4 },
      "dm": { "mode": "idle", "idleMinutes": 240 },
      "group": { "mode": "idle", "idleMinutes": 120 }
    },
    "resetTriggers": ["/new", "/reset"],
    "mainKey": "main"
  }
}

dmScope

main

Control how direct messages are grouped: main (all DMs share main session), per-peer (isolate by sender), per-channel-peer (isolate by channel and sender)

identityLinks

{}

Map provider-prefixed peer IDs to canonical identity so the same person shares a DM session across channels

reset.mode

daily

Reset mode: daily (scheduled time), idle (timeout), or both

reset.atHour

4

Daily reset hour (gateway host local time)

reset.idleMinutes

unset

Idle timeout minutes, session expires if inactive for this duration

resetByType

{}

Set different reset policies for different session types (dm, group, thread)

Inspecting & Managing Sessions

View Session Status

openclaw status

Shows store path and recent sessions

Export All Sessions

openclaw sessions --json

Dump all session entries in JSON format, use --active to filter active sessions

Fetch from Running Gateway

openclaw gateway call sessions.list --params '{}'

Fetch sessions from running gateway (use --url/--token for remote gateway access)

Chat Commands

Send these commands in chat to manage sessions and check status:

/status

Check if agent is reachable, session context usage, current thinking/verbose toggles, and WhatsApp credentials refresh time

/context list

View what's in the system prompt and injected workspace files

/context detail

Show detailed context information including biggest context contributors

/stop

Abort current run, clear queued followups for that session, and stop all sub-agent runs spawned from it

/compact [optional instructions]

Manually compact older context to free up window space, can provide compaction instructions

/new [model]

Start fresh session, optionally specify model alias, provider/model, or provider name

/reset

Reset current session and start fresh conversation

Next Steps