openclaw - 💡(How to fix) Fix sessions.json index bloat: skillsSnapshot duplicated per session entry [1 comments, 2 participants]

Summary

sessions.json (per-agent session index) stores a full skillsSnapshot blob in every entry. This duplicates the entire skills catalog across all sessions, producing a multi-megabyte index for installs with many skills.

Reproduction

On a host running OpenClaw with the main agent and ~140 active session entries (mix of cron/discord/slack/subagent/etc.):

$ ls -la ~/.openclaw/agents/main/sessions/sessions.json
-rw-------  1 user  staff  13368440 ...  sessions.json   # 12.7 MB

Field-size aggregate across all 142 entries (Python json.dumps length per field, summed):

Per-entry skillsSnapshot breakdown (sample from agent:main:cron:8f74506f-...):

• prompt: 17,308 chars (rendered system prompt skills section)
• skills: 4,388 chars (slug list)
• resolvedSkills: 87,601 chars ← dominant bloat, identical across all 142 entries
• version: 13 chars

So 142 × ~87KB of duplicated resolvedSkills content = ~12 MB of avoidable index size.

Impact

• sessions.json is read/rewritten on session lifecycle transitions; rewriting a 12.7MB JSON file on every state change is expensive and amplifies session-write-lock contention. (We've observed [session-write-lock] releasing lock held for 18082ms (max=15000ms) during high-load periods.)
• Memory-resident copy in the gateway process is similarly inflated.
• For users with many skills (this install has ~140), the duplication is roughly proportional to skill_count × session_count.

Proposed fix

Three options, in increasing implementation complexity:

1. Omit resolvedSkills from session-index entries. It's reconstructable from current skills config when needed. Keep prompt and skills slug list if those are needed at restore-time.
2. Store snapshot once globally, reference by hash. Write skillsSnapshot to e.g. ~/.openclaw/agents/main/skills-snapshots.json keyed by sha256 of resolved content. Session entries store skillsSnapshotRef: "sha256:...".
3. Externalize per-session. Move skillsSnapshot into the per-session file under sessions/<id>.json rather than the index.

Option 1 is simplest and likely sufficient; option 2 preserves point-in-time reproducibility (useful if skills change after a session was started) without the duplication.

Additional question

Cron-keyed entries (agent:main:cron:UUID) account for 21% of the index by count (29/142 in this install) but the same per-entry size as everything else. Is there a reason cron sessions need a slot in sessions.json at all? They're isolated by design and don't carry persistent conversation state across runs. Could be a separate ticket.

Environment

• OpenClaw installed from npm at /opt/homebrew/lib/node_modules/openclaw/ (macOS, M-series, node v22)
• Single-user setup, ~140 skills in catalog
• Diagnostic timestamp: 2026-05-05