Session State Tracker Skill

Version: 1.0.0
Author: qsmtco
License: MIT

Overview

The Session State Tracker solves the problem of context loss during OpenClaw session compaction and restarts. It provides a persistent SESSION_STATE.md file that keeps your current project, task, status, and next steps readily available.

Key Features

• Manual or automatic state maintenance – Agent can update SESSION_STATE.md after significant progress
• Optional integration with pre-compaction flush and session transcript indexing for seamless operation
• CLI tools for manual inspection and updates
• No external network access – operates entirely within workspace

Problem Statement

OpenClaw automatically compacts long-running sessions to stay within model context windows. Compaction summarizes older messages and removes them from active context. This leads to loss of conversational continuity:

• The agent forgets the current task and next steps
• Users must repeatedly re-explain what they're working on
• Long-running projects become fragmented

Existing mechanisms (MEMORY.md, daily logs) are for curated long-term memory, not for current working context. We need a lightweight, always-present anchor that survives compaction.

Solution Architecture

The solution is built around a simple file (SESSION_STATE.md) and optional OpenClaw features:

1. SESSION_STATE.md — A small Markdown file with YAML frontmatter storing current state
2. Optional: Pre-compaction memory flush customization – Instructs the agent to verify/update the state file before compaction occurs
3. Optional: Session transcript indexing (memorySearch.experimental.sessionMemory = true) – Enables memory_search to retrieve verbatim details from compacted messages

The skill itself provides tools to read, write, and discover state. How these tools are used (automatic vs manual) is up to the agent's instructions (e.g., AGENTS.md) and the user's configuration choices.

File Format

SESSION_STATE.md lives in the workspace root:

---
project: "session-state-tracker"
task: "Implement skill with read/write/discover tools"
status: "active"          # active | blocked | done
last_action: "Designed revised architecture"
next_steps:
  - "Create skill skeleton"
  - "Implement state.js"
  - "Write CLI"
updated: "2026-02-14T23:20:00Z"
---

## Context
- Brief freeform notes, constraints, links, etc.

All frontmatter fields are plain strings, arrays, booleans, or numbers. The Context section is for human notes and is preserved but not used programmatically.

Implementation Walkthrough

This section documents how to set up the Session State Tracker system in your OpenClaw installation. The skill itself is self-contained; the following steps are optional configuration that enhances automation.

1. Install the Skill