yoagent-state

Durable memory and lineage for long-running agents.

Agents do not just need logs. They need to remember what failed, what changed, what tested it, who approved it, and why the current project state exists.

yoagent-state is an ActiveGraph-inspired Rust continuity runtime for agent systems. It records append-only events, replays them into a semantic graph, and gives you primitives for goals, tasks, observations, hypotheses, patches, artifacts, evals, decisions, policies, behaviors, replay, and forks.

It helps answer the questions that matter after an agent run:

• What goal was the agent trying to satisfy?
• What task, run, or observation produced this state?
• Why does this patch exist?
• What failure did it address?
• What eval validated it?
• What files or artifacts did it reference?
• Was it approved, rejected, or promoted?

goal -> task -> run -> observation -> failure -> hypothesis -> patch -> artifact -> eval -> decision -> promotion

That line is the common causal spine, not a required linear workflow. A diff is an artifact. Promotion is a patch status transition backed by evals and decisions.

flowchart LR
  goal["goal"]
  task["task"]
  run["run"]
  observation["observation"]
  failure["failure"]
  hypothesis["hypothesis"]
  patch["patch"]
  artifact["artifact"]
  eval["eval"]
  decision["decision"]
  promoted["promoted status"]

  task -- serves --> goal
  run -- produces --> observation
  observation -- observes --> failure
  hypothesis -- explains --> failure
  patch -- addresses --> failure
  patch -- advances --> goal
  patch -- references --> artifact
  patch -- validated_by --> eval
  patch -- approved_by --> decision
  decision -- allows --> promoted

yoagent executes.
yoagent-state remembers.
yoyo evolve improves.

Start in 60 seconds

Add the crate:

cargo add yoagent-state

Run the demo from a local clone:

git clone https://github.com/yologdev/yoagent-state.git
cd yoagent-state
cargo run --example goal_lineage

You should see a lineage report like this:

# Make retry behavior reliable

- id: goal_retry_reliability
- kind: goal
- status: InProgress

## Incoming
- serves <- task_retry_timeout
- blocks <- failure_retry_timeout
- advances <- patch_retry_state

This means the goal is being served by a task, blocked by a failure, and advanced by a patch.

flowchart LR
  task["task_retry_timeout<br/>kind: task"]
  failure["failure_retry_timeout<br/>kind: failure"]
  patch["patch_retry_state<br/>kind: patch"]
  goal["goal_retry_reliability<br/>kind: goal<br/>status: InProgress"]

  task -- serves --> goal
  failure -- blocks --> goal
  patch -- advances --> goal

To see the patch/eval/decision lane:

cargo run --example patch_eval_decision

Run the full test suite:

cargo test

Try local JSONL persistence:

cargo run --bin yoagent-state -- init
cargo run --bin yoagent-state -- graph
YOAGENT_STATE_EVENTS=.yoyo/state/events.jsonl cargo run --bin yoagent-state -- events

What it does

yoagent-state gives long-running agents durable continuity without taking over your project.

• Records append-only events for goals, tasks, runs, observations, model calls, tool calls, failures, hypotheses, patches, evals, decisions, and artifacts.
• Replays events into a small semantic graph projection.
• Tracks goal/task lineage and patch lifecycle from proposal to approval, rejection, or promotion.
• References real project artifacts such as diffs, commits, logs, eval output, and files.
• Supports typed packs, policy gates, behavior subscriptions, replay, fork, and diff primitives.
• Exposes lineage queries so agents and humans can explain why state exists.

Git still owns concrete project changes. yoagent-state stores why those changes happened, what tested them, and what they mean.

When you need this

Use yoagent-state when:

• your agent runs longer than one prompt
• you need to explain why a code change exists
• you want eval and decision history attached to patches
• you want durable state without adopting a workflow engine or graph database
• you are building on yoagent, yoyo evolve, or another Rust agent loop

You probably do not need it for one-off scripts, stateless chat flows, or projects where Git commit messages already capture enough context.

Minimal Rust example

use serde_json::json;
use yoagent_state::{ActorRef, MemoryEventStore, NodeId, StateOp, YoAgentState};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let state = YoAgentState::load(MemoryEventStore::new()).await?;
    let failure = NodeId::new("failure_1");

    state.apply_ops(
        ActorRef::agent("demo"),
        vec![StateOp::CreateNode {
            id: failure.clone(),
            kind: "failure".to_string(),
            props: json!({ "title": "retry state lost after timeout" }),
        }],
    ).await?;

    print!("{}", state.lineage(failure).await.to_markdown());
    Ok(())
}

What it is not

yoagent-state is intentionally small.

• not a replacement for Git
• not a workflow engine
• not a graph database
• not a full project database
• not a universal agent framework
• not a hidden self-modification system

The motto is simple but effective.

Documentation

Hosted docs:

https://yologdev.github.io/yoagent-state/

Run the mdBook locally:

mdbook serve docs

If mdbook is not installed:

cargo install mdbook

If Cargo's binary directory is not on your PATH, run it directly:

~/.cargo/bin/mdbook serve docs

GitHub Pages is deployed by .github/workflows/docs.yml. In the GitHub repo settings, Pages source should be set to GitHub Actions.

For coding agents

Read AGENTS.md before modifying the repo. It explains the project boundary, core files, test commands, and the simple-but-effective design rule.

Roadmap

The future plan is tracked in ROADMAP.md and mirrored in the mdBook guide.

Acknowledgments

The core idea for yoagent-state comes from Yohei Nakajima and his ActiveGraph work. This project is an independent Rust implementation inspired by that idea, with a Rust-first architecture for yoagent and yoyo evolve. See ACKNOWLEDGMENTS.md.

License

Licensed under the MIT license.