Plugin Session Carryover

README

# openclaw-plugin-session-carryover

OpenClaw plugin that preserves session context across daily resets.

## Problem

OpenClaw's daily session reset (default: 4 AM) archives the conversation transcript and starts a new session. The agent loses all context from the previous conversation — it doesn't know what was discussed, what decisions were made, or what the user's last request was.

While workspace files (MEMORY.md, etc.) provide some continuity, they don't capture the conversational flow. The agent wakes up with amnesia every morning.

## How It Works

1. **On `session_end`** (reason: `daily` or `idle`):
   - Reads the archived transcript file
   - Extracts the last N user/assistant messages (skipping NO_REPLY, HEARTBEAT_OK, etc.)
   - Writes them to a pending file (`~/.openclaw/session-carryover/<sessionKey>.txt`)
   - Also attempts `enqueueSystemEvent` (may not arrive in time due to fire-and-forget timing)

2. **On `session_start`**:
   - Checks for a pending carryover file
   - If found, injects the content as a system event into the new session
   - Cleans up the pending file

The agent sees the tail of the previous conversation as a `[Session carryover]` block in its system context.

## Configuration

| Option | Type | Default | Description |
|---|---|---|---|
| `tailMessages` | `number` | `20` | Number of tail messages to carry over |
| `maxChars` | `number` | `8000` | Max total characters for carryover |
| `reasons` | `string[]` | `["daily", "idle"]` | Session end reasons that trigger carryover |
| `exclude` | `string[]` | `["*:cron:*"]` | Session key patterns to exclude |

## Installation

Copy to `~/.openclaw/extensions/session-carryover/` and restart the gateway.

## Known Limitation

The `session_end` hook is fire-and-forget — the gateway doesn't wait for it to complete before moving on. The `enqueueSystemEvent` call in `session_end` may not complete before `rebuildPromptBodies()` drains the queue. The file-based fallback (`session_start` → read file → enqueue) handles this race condition.

However, `session_start` is also fire-and-forget. If both hooks lose the race, the carryover file persists on disk and will be picked up the **next** time the session starts (e.g., on the second message).

## Background

See `docs/daily-reset-analysis.md` for the full analysis of OpenClaw's daily reset mechanism and its side effects.

## License

MIT