Git Agent State Protocol · status: buildable

The repo is the agent.

GASP is a git-native standard for portable agent state. An append-only event log folds into a typed graph of goals, patches, evals, and decisions — point any conformant runtime at the repo URL and the same agent resumes anywhere, on any model.

Read the spec Run the checker
$ cargo run -q -- fixture --fixture # verify the fixture, all 7 checks
01 — THE PROBLEM

Agent state today is trapped

Swapping models means amnesia — because the state was never yours to begin with.

Transcripts rot in vendor folders

Session logs pile up in undocumented formats you don't own and can't parse tomorrow.

Memory dies with the runtime

Identity, skills, and learnings live inside one harness. Switch tools and the agent forgets who it is.

Nothing explains why

No lineage from goal to change to test to decision — just a flat transcript of what happened.

02 — HOW IT WORKS

The log folds into a graph

One run from the spec's worked example: a skill patch is proposed, tested, and promoted. Domain events record the why; each state.ops_applied event folds into the graph.

state/events.jsonl append-only · source of truth
folded graph queryable · regenerable
APPEND

Every semantic moment is one JSONL line — goals, runs, tool calls, evals, decisions.

{"kind":"eval.finished","payload":{"status":"Passed"},...}
FOLD

The log folds into a typed graph along the causal spine.

goal → patch → eval → decision → promotion
SHIP

Git commits it, git ships it. The same agent resumes anywhere.

restore = clone + replay
03 — THE MODEL

One repo, two media

An agent has an executor and its state. GASP governs only state — swap the executor freely. Events reference git artifacts; git stores them. Neither duplicates the other.

git owns the concrete what

Code, identity/, skills/, commits, diffs.

lossless bisectable shippable
the log owns the semantic why

Typed events — goals, runs, failures, patches, evals, decisions — committed at state/events.jsonl.

what it was trying to do why each change exists what was decided
THE CAUSAL SPINE — a backbone, not a forced workflow
goal→ task→ run→ observation→ failure→ hypothesis→ patch→ eval→ decision→ promotion
04 — CONFORMANCE

Conformance is a test, not a claim

Five rules, seven mechanical checks, one canonical fixture. Satisfy them and any other conformant runtime can resume your agent — that is what makes GASP a standard and not an API.

1
State lives in a git repo

At the standard layout — log, identity, skills, projections.

2
The event log is append-only

Committed, and using the shared event vocabulary.

3
Identity & skills are artifacts

Committed, loaded at runtime, never compiled in.

4
Restore is clone + replay

Fold the committed log into state; load identity and skills.

5
The executor is swappable

Swapping model or runtime touches .agent/config.toml, nothing else.

verified mechanically

The conformance kit runs 7 checks against any emitted repo — including replay and the pairing rule.

$ conformance-check agent-repo/
[PASS] check 1 — envelope round-trip
[PASS] check 2 — replay
[PASS] check 3 — vocabulary
[PASS] check 4 — append-only in git
[PASS] check 5 — causation integrity
[PASS] check 6 — restore
[PASS] check 7 — domain↔ops consistency
conformant: all checks passed
05 — REPO LAYOUT

Four tiers, not two

Everything in the agent-repo belongs to a tier that says how it may change.

First-class, committed. The log, identity, skills. Append-only; identity is human-gated.
Derived, append-only. Distilled facts — never a history mirror.
Projections, regenerable. Active memory, journal, snapshots. Free to overwrite.
Cold, prunable. Raw transcripts. Never the source of truth.
agent-repo/
├── AGENT.mdmanifest
├── identity/human-gated constitution
├── skills/versioned capabilities
├── state/events.jsonlsource of truth
├── memory/facts.jsonldistilled facts
├── memory/active_memory.mdsynthesis
├── journal/narrative projection
├── transcripts/cold archive
├── snapshots/fast-restore checkpoints
└── .agent/config.tomlexecutor binding
06 — PROOF
yoyo, the octopus agent

yoyo lives here

yoyo, a self-evolving agent with 100k+ lines of self-written Rust, keeps its identity, skills, memory, and lineage in a GASP repo — recording every evolve, skill, and social session since Day 125. Its state repo passes all 7 checks.

"Clone yoyo-gasp and yoyo wakes up knowing who it is."

yoagent executes.
yoagent-state remembers.
yoyo evolve improves.
git ships.
07 — ECOSYSTEM

The ecosystem

$ cargo run -q -- fixture --fixture # verify the fixture
$ cargo run -q -- path/to/agent-repo # verify any repo
$ cargo test # kit self-tests
SPEC.md ↗ The normative protocol — Part I. conformance-check ↗ Fixture + 7-check CLI, in this repo. yoagent-state ↗ Reference runtime, Rust — GitEventStore, lineage, replay, fork.
yoyo-gasp ↗ The first living agent repo.
adapters Claude Code, Codex — spec'd, coming.
github.com/yologdev/gasp ↗ Spec, fixture, checker — everything in one repo.