Metadata

name: session-history
description: Session history system for OpenClaw — persistent, browsable, resumable chat sessions with SQLite index, archive/restore, migration, paginated UI, and chat dropdown integration. Use when: (1) adding session archival/indexing to OpenClaw, (2) implementing session browsing/search in the dashboard, (3) adding session resume/rename/delete, (4) archiving active sessions from the dashboard, (5) adding pagination to session lists, or (6) integrating recent sessions into the chat dropdown.

Session History

Transforms OpenClaw's single-slot session model into a multi-session history system with SQLite indexing, archive/restore, and full dashboard UI.

Architecture

~/.openclaw/agents/{agentId}/sessions/
├── sessions.json           # routing table (unchanged)
├── history.db              # SQLite index (auto-created)
├── {activeSessionId}.jsonl # active transcript
└── archive/
    └── {sessionId}.jsonl   # archived transcripts

Lifecycle:

On /new or session reset → old transcript moves to archive/, metadata indexed in SQLite
On archive (from UI) → session deactivated, transcript archived, indexed, removed from store
On resume → transcript moves back from archive/, SQLite status flips to active
Migration auto-runs on first access: indexes all orphaned .jsonl files

File Map

Backend (new files)

File	Reference	Purpose
`src/config/sessions/history-db.ts`	references/backend-history-db.ts.txt	SQLite CRUD operations
`src/config/sessions/history-migration.ts`	references/backend-history-migration.ts.txt	One-time migration + `initHistoryDbWithMigration`
`src/gateway/session-archive.ts`	references/backend-session-archive.ts.txt	Archive/restore logic

Backend (modified files)

File	Reference	Purpose
`src/gateway/protocol/schema/sessions.ts`	references/backend-protocol-schemas.ts.txt	TypeBox schemas for new RPCs
`src/gateway/server-methods/sessions.ts`	references/backend-rpc-handlers.ts.txt	5 RPC handler implementations

Frontend (modified files)

File	Reference	Purpose
`ui/src/ui/controllers/sessions.ts`	references/frontend-controllers-sessions.ts.txt	Full controller with archived session CRUD + pagination
`ui/src/ui/views/sessions.ts`	references/frontend-views-sessions.ts.txt	Full view with Session History section, Archive button, pagination
`ui/src/ui/app-view-state.ts`	references/frontend-state-changes.txt	State + app.ts + app-render.ts + app-chat.ts + app-settings.ts + app-render.helpers.ts wiring

Installation

See references/INSTALL.md for step-by-step instructions.

RPC Endpoints

Method	Params	Purpose
`sessions.archive`	`key`	Archive active session — deactivates, moves transcript, indexes in SQLite, removes from store
`sessions.archived`	`agentId?, limit?, offset?, search?, status?`	List archived sessions with pagination and search
`sessions.resume`	`sessionId, agentId?`	Restore archived session to active
`sessions.rename`	`sessionId, displayName, agentId?`	Update session display name
`sessions.deleteArchived`	`sessionId, agentId?, deleteTranscript?`	Delete archived session + optional transcript

UI Features

Sessions Page

Active Sessions grid — with Archive button (hidden for Main Session), History, Delete
Session History section — archived sessions with search, Resume/Rename/Delete buttons
Pagination — both sections have 10/20/25 page-size dropdown + Prev/Next

Chat Dropdown

Filters out cron/subagent/openai sessions (only user-facing sessions shown)
"Recent Sessions" <optgroup> with 10 most recent archived sessions
"📋 View All Sessions" link navigates to Sessions tab
Selecting an archived session auto-resumes it

Key Design Decisions

SQLite over JSON: Supports search, pagination, and indexing without loading everything into memory
Server-side pagination for archives: Pass limit/offset to sessions.archived RPC
Client-side pagination for live sessions: Slice the already-loaded array
sessionId-based dropdown values: Archived sessions all share the same sessionKey (agent:main:main), so the dropdown uses __archived__:{sessionId} as the option value
sessions.archive reuses sessions.delete param schema: Both need just { key }

Common Pitfalls

RPC handler signature: Must use ({ params, respond }) destructuring, not (request, respond)
assertValidParams: Takes 4 args: (params, validator, "method.name", respond)
Sessions directory: Use resolveSessionTranscriptsDirForAgent(agentId) — NOT resolveGatewaySessionStoreTarget(config)
Pagination on every load: All loadArchivedSessions calls must pass limit and offset
Page reset: Changing page size or search query must reset page to 1
Archived session dropdown filtering: Filter by sessionId, not sessionKey (all archived sessions share the same sessionKey)

Session History Enhanced

安装技能