neuron-state-fs

Filesystem-backed StateStore for neuron — durable, zero-dependency persistence

Overview

neuron-state-fs implements the StateStore trait from layer0 using the local filesystem. Each key maps to a file inside a configurable base directory, using a safe filename encoding. Reads and writes are async (Tokio fs).

Use it for:

• Single-machine agents that need durable state across restarts
• Development when you want to inspect state without a database
• Sidecar deployments with a shared volume

For ephemeral / test use, prefer neuron-state-memory.

Usage

[dependencies]
neuron-state-fs = "0.4"

use neuron_state_fs::FsStateStore;
use layer0::StateStore;
use std::sync::Arc;

let store: Arc<dyn StateStore> = Arc::new(
    FsStateStore::new("/var/lib/my-agent/state")
);

store.write("session:42:plan", plan_bytes).await?;
let plan = store.read("session:42:plan").await?;

Part of the neuron workspace

neuron is a composable async agentic AI framework for Rust. See the book for architecture and guides.