Session State Tracker

Persistent session state management across compaction and restarts via lifecycle hooks

External Endpoints

This skill does not call any external endpoints. All operations are local to the workspace.

Security & Privacy

• Fully local operation: No network access; all state is stored in SESSION_STATE.md within the workspace.
• File scope: The skill reads and writes only SESSION_STATE.md in the workspace root. No other files are accessed.
• Session discovery: The session_state_discover tool uses memory_search, which may query indexed session transcripts. This is governed by your OpenClaw memorySearch configuration (local vector DB). No external API calls are made by the skill itself.
• No data exfiltration: Nothing leaves your machine unless you have configured external memory backends separately.

Model Invocation Note

The skill registers three lifecycle hooks:

• pre-compaction: runs automatically before compaction to persist state.
• post-compaction: runs automatically after compaction to inject a state reminder.
• session-start: runs automatically at session start to load fresh state.

These hooks are triggered by OpenClaw's core; no agent intervention is required. The tools (session_state_read, session_state_write, session_state_discover) are available for manual use when desired.

Trust Statement

By using this skill, all state management remains local and transparent. The code is open-source and operates solely on your SESSION_STATE.md file. Only install if you trust the author and understand the hook automation.

---

Overview

The Session State Tracker solves context loss during OpenClaw session compaction and restarts by automatically persisting and restoring working state through lifecycle hooks.

Key Features

• Automatic state persistence via OpenClaw hooks (no manual steps during compaction).
• Schema-validated state file (SESSION_STATE.md) with YAML frontmatter.
• Atomic writes to prevent corruption.
• Discovery tool to rebuild state from session transcripts if needed.
• CLI for manual inspection and updates.
• Zero external dependencies beyond Node.js and js-yaml.

---

File Format

SESSION_STATE.md (workspace root):

---
project: "my-project"
task: "Describe current task"
status: "active"          # active | blocked | done | in-progress
last_action: "Latest update"
next_steps:
  - "Step 1"
  - "Step 2"
updated: "2026-02-14T23:20:00.000Z"
---

## Context
Optional freeform notes, constraints, links, etc.

All frontmatter fields are required except body (the Context section). Timestamps must be ISO 8601.

---

Installation

clawhub install qsmtco/session-state-tracker

Or copy the skill folder into skills/session-state-tracker/ and enable in openclaw.json:

"skills": { "entries": { "session-state-tracker": { "enabled": true } } }

Then restart the gateway.

---

Configuration

The skill works out of the box with hooks enabled. Ensure session transcript indexing is active for session_state_discover to be effective:

"agents": {
  "defaults": {
    "memorySearch": {
      "sources": ["memory", "sessions"],
      "experimental": { "sessionMemory": true }
    }
  }
}

No other configuration required.

---

Tools

• session_state_read – read current state (frontmatter + body)
• session_state_write – update fields (auto-timestamps, validates schema)
• session_state_discover – synthesize state from recent sessions and write it

---

CLI

# Show state
session-state show

# Update a field
session-state set task "New task"
session-state set next_steps '["A","B"]'

# Refresh from session transcripts (requires memory_search)
session-state refresh

# Clear state
session-state clear

---

How It Works

1. Session start: session-start hook reads SESSION_STATE.md; if present and fresh (<24h), injects a summary into the initial system context.
2. During work: You may call session_state_write to record progress. The file is the single source of truth.
3. Pre-compaction: pre-compaction hook automatically saves the current state (via discovery if needed) without agent involvement.
4. Post-compaction: post-compaction hook injects a [State Anchor] reminder so the agent re-anchors instantly.
5. Restart: The cycle repeats; state persists across restarts.

---

Migration from v1.x

v2.0.0 introduces lifecycle hooks. No changes to SESSION_STATE.md format. To upgrade:

• Install v2.0.0 (or later).
• Ensure the skill is enabled.
• The hooks replace the old memoryFlush.prompt convention; you may remove any custom prompt from your config.
• Existing SESSION_STATE.md files continue to work unchanged.

---

Troubleshooting

• Hooks not firing? Verify the skill is enabled and the plugin manifest (openclaw.plugin.json) is present. Restart the gateway after installation.
• session_state_discover returns empty? Enable session transcript indexing (memorySearch.experimental.sessionMemory = true) and ensure recent conversation exists.
• State file not updating? Check file permissions; the skill writes atomically to SESSION_STATE.md in the workspace root.

---

Minimal, reliable, and automatic.