Docs / Developers / Memory model

Memory model

CloudyBot keeps context in layers so integrators can reason about what persists, what summarizes, and what resets. Memory is scoped to thread_id — not global per user. User guide: threads & memory. System context: architecture.

Three storage layers

• Pinned memory (user_memory in SQLite) — per-thread key/value strings the user wants always in context. Never summarized. Injected into the system prompt every turn. API: GET/PUT/DELETE /api/user/memory?threadId=….
• Rolling memory (conversations table) — summary (older turns) plus messages JSON (last five verbatim turns after summarization). display_messages keeps the full transcript for the dashboard UI only.
• OpenClaw session (*.jsonl on the gateway) — tool continuity and provider session state. Dashboard sessions use key {userId}--{threadId}; channels use channel-specific keys.

Billing (AI credits, browser minutes) is per userId; conversation memory is per threadId.

What the model sees each turn

Typical prompt assembly order:

1. Base system instructions and model identity hint.
2. Pinned block (if any keys exist for the thread).
3. Specialist persona / duty instructions (when applicable).
4. Conversation summary (if present).
5. Browser and session-rotation hints when relevant.
6. Recent message list — last five turns from messages, trimmed under MAX_CONTEXT with the system block.

Saved browser credentials are appended to the system prompt at chat time; they are not stored in the visible message transcript.

Summarization

After an assistant reply, if stored messages.length >= 10, the API summarizes older turns and keeps only the last 5 in messages. Older content moves into summary. Summarization itself consumes AI credits like any other turn.

The UI still reads display_messages for full scrollback until plan retention purges the thread row. See data & privacy for retention days by tier.

Session rotation (OpenClaw)

The gateway session file may be cleared when:

• Idle longer than SESSION_IDLE_MINUTES (default 30).
• JSONL size exceeds SESSION_MAX_FILE_BYTES (default 200 KB).
• Thread delete or explicit clear flows archive the session.

Rotation does not delete SQLite rolling memory — only the OpenClaw-side tool state. rotateSessionIfNeeded(userId, threadId) runs before outbound agent calls.

Integrator implications

• Always pass a stable threadId on POST /chat — memory will not carry to a new id.
• Use pinned memory for standing rules; use Specialist instructions for role playbooks.
• Long threads lose verbatim early detail but keep gist in summary — re-paste critical facts if needed.
• Deleting a thread removes its conversations row and pinned keys for that id.

Instruction layers (product vs user data)

• System instructions — product-wide safety and formatting baselines.
• Specialist instructions — persona and duties for hired roles.
• Saved facts — user-approved pinned strings per thread.

Related: API reference · repo docs/CONVERSATION-MEMORY-BIG-PICTURE.md · api/features/conversation/conversation-store.js