Skip to content

state-a2ml

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

state-a2ml

README.adoc

STATE

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.a2ml) in A2ML (Annotated Markup Language)

  • Human-readable TOML-like key-value 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.a2ml
  4. Says: "Download STATE.a2ml now - you'll upload it next session"

Start of Next Conversation

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

Technology Stack

Language: A2ML (Annotated Markup Language)

  • TOML-like key-value format, human-readable

  • Machine-parseable with standard TOML tooling

  • Typed and verified document format

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

Containers: Wolfi base image with Guix

File Structure

The STATE.a2ml 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.

Questions for Maintainer (Advanced)

Categorized questions requiring human input. Prevents AI from making assumptions.

Categories: architecture, priorities, integration, deployment, testing, community

Long-Term Roadmap (Advanced)

Extended roadmap with:

  • post-v1 - Planned releases after initial major version

  • vision-items - Aspirational features without timeline

  • research-tracks - Exploratory work with goals and status

State Summary (Advanced)

Quick-reference snapshot for AI to assess project health at a glance.

[state-summary]
project = "My Project"
version = "0.2.0"
overall-completion = 55
next-milestone = "v0.3"
critical-blockers = 0
high-priority-issues = 3
updated = "2025-12-08"

Files in This Repository

Core

  • STATE.a2ml - Template state file

  • lib/ - Modular library

  • 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.a2ml structure

  • ✓ Project metadata encoding

  • ✓ Session checkpoint

  • ✓ Manual download/upload cycle

Phase 2: Smart Queries

  • ✓ Modular architecture

  • ✓ GraphViz DOT visualization

  • ✓ Mermaid diagram generation

  • ✓ History tracking

  • ✓ Velocity calculation

  • ✓ Time estimation

Phase 3: Automation

  • ❏ Elixir service for STATE.a2ml 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

PMPL-1.0-or-later. See LICENSE.txt for details.

Author

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