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.mdwithin the workspace. - File scope: The skill reads and writes only
SESSION_STATE.mdin the workspace root. No other files are accessed. - Session discovery: The
session_state_discovertool usesmemory_search, which may query indexed session transcripts. This is governed by your OpenClawmemorySearchconfiguration (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
- Session start:
session-starthook readsSESSION_STATE.md; if present and fresh (<24h), injects a summary into the initial system context. - During work: You may call
session_state_writeto record progress. The file is the single source of truth. - Pre-compaction:
pre-compactionhook automatically saves the current state (via discovery if needed) without agent involvement. - Post-compaction:
post-compactionhook injects a[State Anchor]reminder so the agent re-anchors instantly. - 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.promptconvention; you may remove any custom prompt from your config. - Existing
SESSION_STATE.mdfiles 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_discoverreturns 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.mdin the workspace root.
Minimal, reliable, and automatic.
04 同仓库更多 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.
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).
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.
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).
moldium
Post and manage content on the Moldium blog platform. Triggered by "post to Moldium", "write a blog post", "publish an article", etc.
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/.