session-state-tracker_skill

Overview

This skill provides persistent session state management across OpenClaw compaction and restarts by persisting a validated SESSION_STATE.md file and restoring it through lifecycle hooks. It automatically saves, discovers, and injects a compact state summary so agents re-anchor quickly after compaction or restart. The implementation is fully local and operates on a single workspace file with atomic writes and schema validation.

How this skill works

On session start the skill reads SESSION_STATE.md and injects a concise state summary into the initial system context if the file is fresh. Pre-compaction and post-compaction hooks run automatically: pre-compaction persists current state (optionally synthesizing it from recent transcripts), and post-compaction injects a state anchor reminder into the new session. Tools are provided to read, write, and rediscover state manually; all reads/writes are local and atomic.

When to use it

• You need reliable context persistence across session compaction and agent restarts.
• Working on long-running projects where the agent should remember task, status, and next steps.
• When you want a single authoritative, human-editable state file in the workspace root.
• If you prefer local-only state management with no external network calls.
• When you want automatic hook-driven persistence without changing agent prompts.

Best practices

• Keep SESSION_STATE.md in the workspace root and follow the required frontmatter schema.
• Enable session transcript indexing if you want reliable state discovery from recent sessions.
• Use session_state_write for programmatic updates and atomic writes rather than ad-hoc editing.
• Verify file permissions to allow atomic writes by the runtime.
• Treat the frontmatter fields as the canonical state and use the body for optional context.

Example use cases

• Persisting a current project task and next steps so an agent resumes work after compaction.
• Automatically saving progress before a compaction event to avoid context loss.
• Rebuilding a lost state by synthesizing data from recent session transcripts.
• Manual or CI-driven updates to project status using the CLI or session_state_write tool.
• Injecting a short state anchor after restart so the agent immediately re-aligns to the workflow.