session-state-tracker

跨压缩和通过生命周期挂钩重新启动的持久会话状态管理

## 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):

```markdown
---
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

```bash
clawhub install qsmtco/session-state-tracker
```

Or copy the skill folder into `skills/session-state-tracker/` and enable in `openclaw.json`:

```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:

```json
"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

```bash
# 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.**

---

## 中文说明

## 外部端点

此技能不调用任何外部端点。所有操作均在工作区本地进行。

## 安全与隐私

- **完全本地运行**：无网络访问；所有状态都存储在工作区内的 `SESSION_STATE.md` 中。
- **文件范围**：此技能仅读写工作区根目录中的 `SESSION_STATE.md`。不访问任何其他文件。
- **会话发现**：`session_state_discover` 工具使用 `memory_search`，它可能查询已索引的会话记录。这受你的 OpenClaw `memorySearch` 配置（本地向量数据库）管辖。技能本身不进行任何外部 API 调用。
- **无数据外泄**：除非你单独配置了外部记忆后端，否则没有任何内容离开你的机器。

## 模型调用说明

此技能注册了三个生命周期挂钩：
- `pre-compaction`：在压缩前自动运行以持久化状态。
- `post-compaction`：在压缩后自动运行以注入状态提醒。
- `session-start`：在会话开始时自动运行以加载最新状态。

这些挂钩由 OpenClaw 的核心触发；无需代理介入。这些工具（`session_state_read`、`session_state_write`、`session_state_discover`）可在需要时供手动使用。

## 信任声明

使用此技能时，所有状态管理均保持本地化和透明。代码是开源的，且仅在你的 `SESSION_STATE.md` 文件上运行。仅在你信任作者并理解挂钩自动化的情况下才安装。

---

## 概览

Session State Tracker 通过生命周期挂钩自动持久化和恢复工作状态，解决了 OpenClaw 会话压缩和重启期间的上下文丢失问题。

### 关键特性

- 通过 OpenClaw 挂钩**自动持久化状态**（压缩期间无需手动步骤）。
- **经 schema 验证的状态文件**（`SESSION_STATE.md`），带 YAML frontmatter。
- **原子写入**以防止损坏。
- **发现工具**，可在需要时从会话记录重建状态。
- **CLI**，用于手动检查和更新。
- 除 Node.js 和 `js-yaml` 外**零外部依赖**。

---

## 文件格式

`SESSION_STATE.md`（工作区根目录）：

```markdown
---
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.
```

除 `body`（Context 部分）外，所有 frontmatter 字段都是必填的。时间戳必须为 ISO 8601。

---

## 安装

```bash
clawhub install qsmtco/session-state-tracker
```

或将技能文件夹复制到 `skills/session-state-tracker/` 并在 `openclaw.json` 中启用：

```json
"skills": { "entries": { "session-state-tracker": { "enabled": true } } }
```

然后重启网关。

---

## 配置

此技能在启用挂钩后开箱即用。确保会话记录索引处于活动状态，以便 `session_state_discover` 有效：

```json
"agents": {
  "defaults": {
    "memorySearch": {
      "sources": ["memory", "sessions"],
      "experimental": { "sessionMemory": true }
    }
  }
}
```

无需其他配置。

---

## 工具

- `session_state_read` – 读取当前状态（frontmatter + body）
- `session_state_write` – 更新字段（自动加时间戳，验证 schema）
- `session_state_discover` – 从近期会话合成状态并写入

---

## CLI

```bash
# 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
```

---

## 工作原理

1. **会话开始**：`session-start` 挂钩读取 `SESSION_STATE.md`；如果存在且为最新（<24 小时），则将摘要注入初始系统上下文。
2. **工作期间**：你可以调用 `session_state_write` 记录进度。该文件是唯一的事实来源。
3. **压缩前**：`pre-compaction` 挂钩自动保存当前状态（必要时通过发现），无需代理参与。
4. **压缩后**：`post-compaction` 挂钩注入 `[State Anchor]` 提醒，使代理即时重新锚定。
5. **重启**：循环重复；状态在重启之间持久化。

---

## 从 v1.x 迁移

v2.0.0 引入了生命周期挂钩。`SESSION_STATE.md` 格式无变化。升级方法：
- 安装 v2.0.0（或更高版本）。
- 确保技能已启用。
- 挂钩取代了旧的 `memoryFlush.prompt` 约定；你可以从配置中移除任何自定义提示。
- 现有的 `S