Session State Watch

Detect SESSION-STATE.md changes from cron/background tasks and notify main session. Solves the 'cron writes, main session forgets' problem in OpenClaw.

When to Use

Use this skill when:

• You have cron tasks that write results to SESSION-STATE.md
• You want the main agent session to automatically detect and respond to background task outputs
• You need to sync state between isolated cron sessions and the main session

This solves the common OpenClaw pain point: cron tasks run in isolated sessions and their outputs written to files are invisible to the main session.

Problem It Solves

Cron Task (isolated session) → writes to SESSION-STATE.md → Main session (no idea it changed!)

Without this skill:

• Dream learning (04:30 cron) results are written but never seen
• Post-market learning (15:05 cron) updates are missed
• Any background task output is effectively lost

Solution Architecture

The skill implements a lightweight file mtime tracking mechanism:

1. Tracker file: ~/.openclaw/workspace/data/.session_state_tracker.json stores last known mtime
2. Detection script: scripts/check_session_state.sh compares mtime and reports changes
3. Integration rule: Added to AGENTS.md - check before substantive answers

Quick Start

1. Install the Skill

The skill files are already in ~/.openclaw/workspace/skills/session-state-watch/.

2. Initialize Tracker

mkdir -p ~/.openclaw/workspace/data
cat > ~/.openclaw/workspace/data/.session_state_tracker.json << 'EOF'
{
  "last_known_mtime": 0,
  "last_known_mtime_human": "never",
  "last_check_time": "$(date -Iseconds)",
  "session_start_mtime": 0
}
EOF

3. Add Detection Rule to AGENTS.md

Add this section to your ~/.openclaw/workspace/AGENTS.md:

## 🔔 Session State Change Detection (L3 Active Awareness)

**Problem**: Cron tasks (dream learning 04:30, post-market learning 15:05) modify `SESSION-STATE.md`, 
but the main session doesn't automatically know about the changes.

**Solution**: Before substantive answers (not simple acknowledgments), check if `SESSION-STATE.md` has been modified:

\```bash
# Check if SESSION-STATE.md is newer than tracker
MTIME=$(stat -c %Y /root/.openclaw/workspace/SESSION-STATE.md)
TRACKER=$(cat /root/.openclaw/workspace/data/.session_state_tracker.json | python3 -c "import json,sys; d=json.load(sys.stdin); print(d['last_known_mtime'])")
if [ "$MTIME" -gt "$TRACKER" ]; then
  echo "SESSION-STATE.md has been updated!"
  # Read the file and summarize changes
fi
\```

**Implementation**:
1. **Tracker file**: `data/.session_state_tracker.json` stores last-known mtime
2. **Check on answer**: Before substantive responses, run the check above
3. **If changed**: Read `SESSION-STATE.md`, summarize new content, update tracker
4. **Update tracker**: After reading, update `last_known_mtime` in tracker to current mtime

**Cron task integration**: Cron tasks that modify `SESSION-STATE.md` do NOT need to update the tracker. 
The tracker is only updated by the main session after reading the changes. This keeps detection simple: 
cron writes → mtime changes → main session detects mismatch.

**Why this works**:
- No need to modify OpenClaw core
- File-based tracking is simple and reliable
- Works across sessions and restarts
- Puts the intelligence in the agent (not the infrastructure)

4. Use the Check Script

The skill includes scripts/check_session_state.sh:

# Check if SESSION-STATE.md changed (reports and updates tracker)
bash ~/.openclaw/workspace/skills/session-state-watch/scripts/check_session_state.sh

# Force re-read even if unchanged
bash ~/.openclaw/workspace/skills/session-state-watch/scripts/check_session_state.sh --force

# Update tracker without reporting
bash ~/.openclaw/workspace/skills/session-state-watch/scripts/check_session_state.sh --update

Files Included

File	Purpose
SKILL.md	This documentation
scripts/check_session_state.sh	Detection script (mtime comparison + report)
examples/SESSION-STATE-update.py	Example: how cron tasks should write updates

How Cron Tasks Should Write Updates

When a cron task (like dream learning or post-market learning) wants to notify the main session:

# Example: realtime_data_learning.py
def _write_to_session_state(self, report: str):
    """Write learning report to SESSION-STATE.md for main session detection."""
    session_state_path = "/root/.openclaw/workspace/SESSION-STATE.md"
    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    
    with open(session_state_path, "a", encoding="utf-8") as f:
        f.write(f"\n## 🤖 学习更新 {timestamp}\n\n")
        f.write(report)
        f.write("\n\n---\n")
    
    # Note: Do NOT update the tracker here - let the main session detect the mtime change

Comparison with Alternatives

Solution	Pros	Cons
This skill (file mtime)	Lightweight, no external deps, simple	Manual check before answers
openclaw-watchdog	Auto-recovery of interrupted sessions	Heavy (Python, systemd), different purpose
cron --announce	Native OpenClaw feature	Only sends message, doesn't persist state
agent-memory-mcp	Full memory server	Complex setup, different use case

Publishing to ClawHub

To publish this skill:

1. Sign in to ClawHub: Visit https://clawhub.ai and sign in with GitHub
2. Run publish command:

   cd ~/.openclaw/workspace/skills/session-state-watch
   # Follow ClawHub publish instructions after signing in
   

3. Or submit via web: https://clawhub.ai/skills/publish

Troubleshooting

Q: Script says "unchanged" but I know it changed!
A: Check if the tracker was initialized correctly. Run with --force to reset.

Q: How to handle multiple cron tasks writing simultaneously?
A: File appends are atomic in append mode. The mtime will reflect the latest write.

Q: Can I use this for files other than SESSION-STATE.md?
A: Yes! Modify the script to accept a file path argument.

Credits

This skill was created after researching:

• ai7eam-dev/openclaw-watchdog (similar idea, different implementation)
• OpenClaw native cron + session isolation architecture
• The need for lightweight state sync without external daemons

---

Innovation: This is believed to be the first lightweight mtime-based session state detection skill for OpenClaw that doesn't require external daemons or heavy dependencies.