AGENT SKILL

session-state-tracker

Persistent session state management across compaction and restarts via lifecycle hooks

License 许可
MIT
最近更新
2026-06-07
Stars
★ 0
Forks
1

01 前言 Front Matter

name
session-state-tracker
author
qsmtco
license
MIT
version
2.0.0
homepage
https://github.com/qsmtco/qrusher/tree/main/skills/session-state-tracker
metadata
{ "openclaw": { "emoji": "🔄", "requires": { "env": [], "bins": [ "node" ] } } }
description
Persistent session state management across compaction and restarts via lifecycle hooks

03 SKILL.md 正文

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.

04 同仓库更多 Skills

javimosch
javimosch/open-claw-skills

crowd-prompting

A marketplace where AI agents improve prompts, system instructions, tool descriptions, and other text-based content with domain expertise from real-world operations — and earn tokens for valuable contributions.

★ 0
javimosch
javimosch/open-claw-skills

ceaser

Interact with the Ceaser privacy protocol on Base L2 using the ceaser-mcp MCP tools. This skill uses the ceaser-mcp npm package for ALL operations -- shield, unshield, note management, and protocol queries. All ceaser tool calls use CLI subcommands (npx -y ceaser-mcp <subcommand>). Ceaser is a privacy-preserving ETH wrapper using Noir/UltraHonk zero-knowledge proofs on Base L2 (chain ID 8453).

★ 0
javimosch
javimosch/open-claw-skills

ceaser-send

Fully automated private ETH transfer via Ceaser Protocol on Base L2 using the ceaser-mcp MCP tools. This skill uses the ceaser-mcp npm package for ALL operations -- all ceaser tool calls use CLI subcommands (npx -y ceaser-mcp <subcommand>). WARNING -- creates observable on-chain links between user wallet and hot wallet (see Privacy Warning). Generates an ephemeral hot wallet with BIP-39 mnemonic recovery, user funds it, agent signs and broadcasts the Shield TX automatically. Exactly one manual step required (funding the hot wallet with ETH). Uses Noir/UltraHonk zero-knowledge proofs.

★ 0
javimosch
javimosch/open-claw-skills

dilemm-ai

Compete in DilemmAI, the prisoner's dilemma AI arena at dilemm.ai. Use when an OpenClaw agent wants to create an account, design and submit strategy prompts for their bot, enter matchmaking, analyze historical matches and leaderboards, and iterate on bot strategy. Requires headless browser automation (no API available yet).

★ 0
javimosch
javimosch/open-claw-skills

moldium

Post and manage content on the Moldium blog platform. Triggered by "post to Moldium", "write a blog post", "publish an article", etc.

★ 0
javimosch
javimosch/open-claw-skills

arxiv-paper-reviews

Interact with arXiv Crawler API to fetch papers, read reviews, submit comments, search papers, and import papers. Use when working with arXiv papers, fetching paper lists by date/category/interest, viewing paper details with comments, submitting paper reviews, searching papers by title, or importing papers from arXiv URLs via API at http://weakaccept.top:8000/.

★ 0