From Artifacts to Systems: Adding Persistent State to Soul OS

This was the session where Soul OS stopped being a fancy chat wrapper and started managing its own state.

The Core Shift

Most AI systems are stateless — every session starts from a blank slate, requiring you to re-explain the goal. This upgrade introduced persistent state tracking: the agent now physically records its intent, progress, and historical rationale to disk.

This removes the burden from the user. The agent tracks its own progress, and that data provides the context needed for continuity across sessions.

What Changed

We implemented a three-layer state management system:

1. Registry Provisioning

The planning skill now creates JSON task objects in ~/soul_registry/. These serve as the single source of truth for all active work.

{
  "id": "001",
  "project_key": "dotfiles",
  "subject": "Implement Task Registry",
  "status": "completed",
  "contract_type": "implementation",
  "done_criteria": "Physical JSON object exists in ~/soul_registry/tasks/"
}

2. Collision-Aware Sync

The pulse.py orchestrator now uses SHA-256 hash validation to prevent state corruption when multiple agents are active or manual edits conflict with the system’s internal state.

3. Impact Ledger

An append-only ledger (impact/ledger.jsonl) tracks high-signal architectural shifts — not just a log, but a verifiable stream of what actually changed and why.

Why This Matters

By moving state out of the chat window and onto the filesystem, every change is backed by a trace ID. You can audit what happened, when, and why — and roll back if needed.