{"skill":{"slug":"session-state-tracker","displayName":"Session State Tracker","summary":"Persistent session state management across compaction and restarts via lifecycle hooks","description":"---\nname: session-state-tracker\ndescription: Persistent session state management across compaction and restarts via lifecycle hooks\nversion: 2.0.0\nauthor: qsmtco\nlicense: MIT\nhomepage: https://github.com/qsmtco/qrusher/tree/main/skills/session-state-tracker\nmetadata:\n  openclaw:\n    requires:\n      bins:\n        - node\n      env: []\n    emoji: \"🔄\"\n---\n\n## External Endpoints\n\nThis skill does not call any external endpoints. All operations are local to the workspace.\n\n## Security & Privacy\n\n- **Fully local operation**: No network access; all state is stored in `SESSION_STATE.md` within the workspace.\n- **File scope**: The skill reads and writes only `SESSION_STATE.md` in the workspace root. No other files are accessed.\n- **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.\n- **No data exfiltration**: Nothing leaves your machine unless you have configured external memory backends separately.\n\n## Model Invocation Note\n\nThe skill registers three lifecycle hooks:\n- `pre-compaction`: runs automatically before compaction to persist state.\n- `post-compaction`: runs automatically after compaction to inject a state reminder.\n- `session-start`: runs automatically at session start to load fresh state.\n\nThese 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.\n\n## Trust Statement\n\nBy 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.\n\n---\n\n## Overview\n\nThe Session State Tracker solves context loss during OpenClaw session compaction and restarts by automatically persisting and restoring working state through lifecycle hooks.\n\n### Key Features\n\n- **Automatic state persistence** via OpenClaw hooks (no manual steps during compaction).\n- **Schema-validated state file** (`SESSION_STATE.md`) with YAML frontmatter.\n- **Atomic writes** to prevent corruption.\n- **Discovery tool** to rebuild state from session transcripts if needed.\n- **CLI** for manual inspection and updates.\n- **Zero external dependencies** beyond Node.js and `js-yaml`.\n\n---\n\n## File Format\n\n`SESSION_STATE.md` (workspace root):\n\n```markdown\n---\nproject: \"my-project\"\ntask: \"Describe current task\"\nstatus: \"active\"          # active | blocked | done | in-progress\nlast_action: \"Latest update\"\nnext_steps:\n  - \"Step 1\"\n  - \"Step 2\"\nupdated: \"2026-02-14T23:20:00.000Z\"\n---\n\n## Context\nOptional freeform notes, constraints, links, etc.\n```\n\nAll frontmatter fields are required except `body` (the Context section). Timestamps must be ISO 8601.\n\n---\n\n## Installation\n\n```bash\nclawhub install qsmtco/session-state-tracker\n```\n\nOr copy the skill folder into `skills/session-state-tracker/` and enable in `openclaw.json`:\n\n```json\n\"skills\": { \"entries\": { \"session-state-tracker\": { \"enabled\": true } } }\n```\n\nThen restart the gateway.\n\n---\n\n## Configuration\n\nThe skill works out of the box with hooks enabled. Ensure session transcript indexing is active for `session_state_discover` to be effective:\n\n```json\n\"agents\": {\n  \"defaults\": {\n    \"memorySearch\": {\n      \"sources\": [\"memory\", \"sessions\"],\n      \"experimental\": { \"sessionMemory\": true }\n    }\n  }\n}\n```\n\nNo other configuration required.\n\n---\n\n## Tools\n\n- `session_state_read` – read current state (frontmatter + body)\n- `session_state_write` – update fields (auto-timestamps, validates schema)\n- `session_state_discover` – synthesize state from recent sessions and write it\n\n---\n\n## CLI\n\n```bash\n# Show state\nsession-state show\n\n# Update a field\nsession-state set task \"New task\"\nsession-state set next_steps '[\"A\",\"B\"]'\n\n# Refresh from session transcripts (requires memory_search)\nsession-state refresh\n\n# Clear state\nsession-state clear\n```\n\n---\n\n## How It Works\n\n1. **Session start**: `session-start` hook reads `SESSION_STATE.md`; if present and fresh (<24h), injects a summary into the initial system context.\n2. **During work**: You may call `session_state_write` to record progress. The file is the single source of truth.\n3. **Pre-compaction**: `pre-compaction` hook automatically saves the current state (via discovery if needed) without agent involvement.\n4. **Post-compaction**: `post-compaction` hook injects a `[State Anchor]` reminder so the agent re-anchors instantly.\n5. **Restart**: The cycle repeats; state persists across restarts.\n\n---\n\n## Migration from v1.x\n\nv2.0.0 introduces lifecycle hooks. No changes to `SESSION_STATE.md` format. To upgrade:\n- Install v2.0.0 (or later).\n- Ensure the skill is enabled.\n- The hooks replace the old `memoryFlush.prompt` convention; you may remove any custom prompt from your config.\n- Existing `SESSION_STATE.md` files continue to work unchanged.\n\n---\n\n## Troubleshooting\n\n- Hooks not firing? Verify the skill is enabled and the plugin manifest (`openclaw.plugin.json`) is present. Restart the gateway after installation.\n- `session_state_discover` returns empty? Enable session transcript indexing (`memorySearch.experimental.sessionMemory = true`) and ensure recent conversation exists.\n- State file not updating? Check file permissions; the skill writes atomically to `SESSION_STATE.md` in the workspace root.\n\n---\n\n**Minimal, reliable, and automatic.**","tags":{"latest":"2.0.0"},"stats":{"comments":0,"downloads":388,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":3},"createdAt":1771113785356,"updatedAt":1778491542212},"latestVersion":{"version":"2.0.0","createdAt":1771434214027,"changelog":"v2.0.0: Hook-based automation (pre-compaction, post-compaction, session-start), atomic writes, schema validation, comprehensive tests. Breaks from v1.x by removing convention-based prompts; now fully automatic.","license":null},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"qsmtco","userId":"s17c6trzbwfqeabfg04zjp98cs884arg","displayName":"qsmtco","image":"https://avatars.githubusercontent.com/u/45089207?v=4"},"moderation":null}