Summary

Summary

After running openclaw update, the WebUI usage area appears to lose prior usage history. In practice, the underlying transcript data and usage records still exist on disk, but the WebUI does not present them as a continuous historical view.

This appears to be a backend + UX gap rather than true data loss.

Problem to solve

Problem

Users reasonably expect usage history to survive:

• openclaw update
• Gateway restarts
• /new
• /reset
• logical session re-binding to a new sessionId

Right now, after update/restart, the usage UI can look like history was erased, especially for long-lived logical surfaces like:

• agent:main:main
• agent:main:discord:channel:<id>

What’s actually happening

From local diagnosis:

• Gateway is still running under the same user/home
• ~/.openclaw/agents/<agentId>/sessions/sessions.json still exists
• transcript files ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl still exist
• usage data still exists in transcript files

The issue is that the product currently leans too heavily on the current session-store mapping:

• sessionKey -> current sessionId

When a logical session key gets rebound to a new sessionId after restart/update/reset, the UI effectively follows the new current session instance instead of presenting a historical rollup across prior incarnations of that same logical session surface.

Root cause

OpenClaw is conflating two different things:

1. Current session routing state

• what sessionId currently owns a logical sessionKey

2. Historical usage lineage

• all transcript-backed usage associated with that logical session across resets/restarts/new current instances

As a result, the WebUI makes historical usage feel fragmented or lost whenever a logical session rotates to a new sessionId.

Why updates trigger this visibly

openclaw update restarts the Gateway. After restart:

• the WebUI reconnects
• current store mappings are authoritative for active sessions
• the logical session may now point to a fresh/current sessionId
• prior transcript-backed usage is no longer visually continuous in the main usage experience

So the user perceives a reset even though the transcript data still exists.

Expected behavior

OpenClaw should support a durable usage history experience that survives restarts and updates.

Users should be able to inspect:

• current session instance usage
• historical lineage usage across all prior incarnations of a logical session
• global usage across longer date ranges

The UI should not imply that history was deleted when transcript-backed historical usage still exists.

Proposed solution

Required backend changes

1. Introduce logical session lineage/family aggregation

Add a durable concept such as:

• logicalSessionKey
• sessionFamilyKey
• or similar

This should represent the stable logical surface identity independent of the current sessionId.

Need to resolve for transcript-backed sessions:

• agentId
• sessionId
• lineage/family key
• first activity
• last activity
• usage totals
• cost totals

2. Add lineage-aware usage APIs

Either extend sessions.usage or add a companion endpoint to aggregate by:

• instance
• logical family
• agent
• global total

Example shape:

{
"groupBy": "instance|family|agent|none",
"key": "agent:main:main",
"includeHistorical": true,
"range": "7d|30d|90d|1y|all"
}

3. Add transcript-backed family discovery/indexing

Aggregate usage should be able to roll up all relevant transcript files for a logical session family, ideally via a cached/indexed summary rather than expensive full rescans on every UI load.

4. Keep sessions.json as current-state metadata, not the sole analytics source

Use sessions.json for:

• current routing
• live card/session metadata

Use transcript-backed lineage/index data for:

• historical usage
• cross-restart rollups
• long-range charts

5. Support explicit long-range history queries

The usage layer should support:

• 7d
• 30d
• 90d
• 1y
• all
• custom ranges

and not silently fall back to only recent/default ranges when the user wants historical views.

Required WebUI changes

1. Distinguish “Current instance” vs “Historical lineage”

For session usage views, add an obvious toggle:

• Current instance
• Historical lineage

Definitions should be clear in the UI.

2. Make full history discoverable

If multiple historical instances exist, either:

• default to lineage view, or
• show a prominent message like:
• “This session has 12 historical instances. You are viewing current instance only.”
• CTA: “View full history”

3. Add date-range controls

Add first-class date controls:

• 7d
• 30d
• 90d
• 1y
• all
• custom

4. Show what is included

For lineage views, show:

• number of underlying session instances
• first activity
• last activity
• optional expandable list of included sessionIds

This makes the aggregation understandable and trustworthy.

5. Avoid “history was lost” UX

If current-instance usage is short but historical lineage exists, the UI should say so explicitly.

Examples:

• “Current session started today; historical usage is available.”
• “Gateway restart created a new current session instance; prior usage remains available in lineage view.”

Acceptance criteria

Functional

• After openclaw update, previously visible historical usage remains available in the WebUI
• A logical session spanning multiple transcript files can be viewed as one historical lineage
• Users can switch between current-instance and historical-lineage views
• Usage queries support 7d / 30d / 90d / 1y / all
• Historical usage is derived from transcript-backed data, not only current sessions.json entries

Correctness

• Family totals equal the sum of included transcript instances
• No transcript is double-counted
• Transcripts with unclear lineage are isolated rather than incorrectly merged
• Current-instance behavior remains unchanged when lineage mode is off

UX

• The UI clearly indicates whether it is showing current instance or lineage
• The UI no longer reasonably implies that openclaw update erased history when historical transcript-backed usage still exists

Non-goals

• rewriting old transcript files
• turning sessions.json into a full historical warehouse
• blocking Gateway startup on a full historical reindex

Diagnosis notes

Confirmed locally:

• same user/home before and after diagnosis
• same ~/.openclaw path
• sessions.json populated
• transcript .jsonl files still present
• aggregate usage code already supports transcript scanning

So this looks like a lineage aggregation + presentation gap, not raw data disappearance.

Alternatives considered

Patching my own system locally, but that isn't a long term fix.

Impact

Affected: Me
Severity: Annoyed
Frequency: After every openclaw update
Consequence: Unable to see usage history

Evidence/examples

Diagnosis notes

Confirmed locally:

• same user/home before and after diagnosis
• same ~/.openclaw path
• sessions.json populated
• transcript .jsonl files still present
• aggregate usage code already supports transcript scanning

So this looks like a lineage aggregation + presentation gap, not raw data disappearance.

Additional information

No response