STATE

Table of Contents

• Overview
  • Problem
  • Solution
• Quick Start
  • Development Environment
  • End of Conversation
  • Start of Next Conversation
• Technology Stack
• File Structure
  • Metadata
  • User Context
  • Session Context
  • Focus
  • Project Catalog
  • History
  • Critical Next Actions
• Query System
• Why Scheme?
• Files in This Repository
  • Core
  • Documentation
  • Infrastructure
• Roadmap
  • Phase 1: Foundation ✓
  • Phase 2: Smart Queries ✓
  • Phase 3: Automation
  • Phase 4: Full Integration
• License
• Author

Stateful Context Tracking Engine for AI Conversation Continuity

Overview

STATE is a checkpoint/restore system for AI conversations that persists project context, decisions, and next actions across multiple Claude conversations.

Problem

• Each new Claude conversation starts with zero context about ongoing projects

• Complex project interdependencies get lost between sessions

• Progress gets reset; decisions already made must be repeated

• Token limits force mid-project context loss

Solution

• Single declarative file (STATE.scm) in Guile Scheme

• Human-readable format (not JSON/binary)

• Download at end of session → Upload at start of next

• Claude reads it and resumes exactly where you left off

• Includes: current project focus, blockers, next actions, completion percentages

Quick Start

Development Environment

Primary (Guix):

guix shell -m manifest.scm
just test

Fallback (Nix):

nix develop
just test

Container (Wolfi + Guix):

nerdctl build -t state:latest .
nerdctl run -it --rm state:latest

End of Conversation

User: "Create STATE handover and prepare for next session"
Claude:
  1. Updates all project completion percentages
  2. Lists critical blockers
  3. Exports STATE.scm
  4. Says: "Download STATE.scm now - you'll upload it next session"

Start of Next Conversation

User: [Uploads STATE.scm] "Continue from this state"
Claude:
  1. Reads and parses STATE.scm
  2. Reconstructs project context
  3. Identifies current focus
  4. Picks up exactly where last conversation left off

Technology Stack

Language: Guile Scheme (GNU’s Scheme implementation)

• Minimal, readable, homoiconic (code = data)

• minikanren-like patterns for constraint/logic queries over project state

Package Management: Guix (primary), Nix (fallback)

Containers: Wolfi base image with Guix

File Structure

The STATE.scm file contains these major sections:

Metadata

Format version and timestamps for tracking state evolution.

User Context

Name, roles, language preferences, tool preferences, and values.

Session Context

Conversation ID, message counts, and token limit status.

Focus

Current project, phase, deadlines, and blocking dependencies.

Project Catalog

Complete list of all projects with:

• Status (in-progress, blocked, paused, complete, abandoned)

• Completion percentage

• Category and phase

• Dependencies and blockers

• Next actions

History

Completion snapshots over time for velocity tracking and estimation.

Critical Next Actions

Prioritized list of immediate actions with optional deadlines.

Query System

STATE supports minikanren-style relational queries:

;; Load the library
(add-to-load-path "lib")
(use-modules (state))

;; What's my current focus?
(get-current-focus state)
;; -> "Oblibeny parser implementation"

;; What projects are blocked?
(get-blocked-projects state)
;; -> (project-alist ...)

;; minikanren relational query
(run* (q) (statuso q "blocked" state))
;; -> ("My Language Solo" "ZeroStep" "Aletheia")

;; Generate dependency graph
(generate-dot state)      ; GraphViz DOT
(generate-mermaid state)  ; Mermaid diagram

Why Scheme?

1. Minimal syntax - S-expressions are almost self-explanatory

2. Lisp tradition - Code-as-data matches logic programming

3. Portable - Runs on Linux, macOS, Windows (via WSL)

4. GNU standard - Free Software Foundation standard for extensibility

5. Human-readable - Easier to read and edit than JSON

Comparison:

;; Scheme: minimal syntax, obvious structure
(project-name . "VALUE")

;; JSON: noise-heavy
{"projectName": "VALUE"}

Files in This Repository

Core

• STATE.scm - Template state file

• lib/ - Modular Scheme library

  • state-core.scm - Core accessors and predicates

  • state-kanren.scm - minikanren integration

  • state-graph.scm - GraphViz/Mermaid visualization

  • state-history.scm - Velocity tracking and estimation

  • state.scm - Main entry point

• examples/ - Example state files

Documentation

• README.adoc - This documentation

• USAGE.adoc - Comprehensive usage guide

• CHANGELOG.adoc - Version history

• CONTRIBUTING.adoc - Contribution guidelines

• GOVERNANCE.adoc - Project governance

• CODE_OF_CONDUCT.adoc - Community standards

Infrastructure

• channels.scm - Guix channel definition

• manifest.scm - Guix package manifest

• guix.scm - Guix package definition

• flake.nix - Nix flake (fallback)

• Containerfile - Wolfi + Guix container

• justfile - Task automation

• .gitlab-ci.yml - CI/CD pipeline

Roadmap

Phase 1: Foundation ✓

• ✓ Basic STATE.scm structure

• ✓ Project metadata encoding

• ✓ Session checkpoint

• ✓ Manual download/upload cycle

Phase 2: Smart Queries ✓

• ✓ Modular architecture

• ✓ minikanren integration (with fallback)

• ✓ GraphViz DOT visualization

• ✓ Mermaid diagram generation

• ✓ History tracking

• ✓ Velocity calculation

• ✓ Time estimation

Phase 3: Automation

• ❏ Elixir service for STATE.scm read/write

• ❏ Integration with Echomesh for automatic state capture

• ❏ Periodic exports

• ❏ Diff tracking

Phase 4: Full Integration

• ❏ UPM (Universal Project Manager) integration

• ❏ Git hooks for auto-update on commits

• ❏ Team collaboration features

License

Dual licensed under MIT OR AGPL-3.0-or-later (your choice). The Palimpsest principles are encouraged but not legally required. See LICENSE.txt for details.

Author

Designed by Jonathan D.A. Jewell
Implemented with Claude assistance
December 2025