Use File Store

Use this when you need file-based persistence for threads, runs, and messages without an external database.

Prerequisites

awaken-stores crate with the file feature enabled

Steps

Add the dependency.

[dependencies]
awaken-stores = { version = "...", features = ["file"] }

Or, if using the awaken facade crate (which re-exports awaken-stores), add awaken-stores directly for the feature flag:

[dependencies]
awaken = { package = "awaken-agent", version = "..." }
awaken-stores = { version = "...", features = ["file"] }

Create a FileStore.

use std::sync::Arc;
use awaken::stores::FileStore;

let store = Arc::new(FileStore::new("./data"));

The directory is created automatically on first write. The layout is:

./data/
  threads/<thread_id>.json
  messages/<thread_id>.json
  runs/<run_id>.json

Wire it into the runtime.

use awaken::AgentRuntimeBuilder;

let runtime = AgentRuntimeBuilder::new()
    .with_thread_run_store(store)
    .with_agent_spec(spec)
    .with_provider("anthropic", Arc::new(provider))
    .build()?;

Use an absolute path for production.

use std::path::PathBuf;

let data_dir = PathBuf::from("/var/lib/myapp/awaken");
let store = Arc::new(FileStore::new(data_dir));

Verify

Run the agent, then inspect the data directory. You should see JSON files under threads/, messages/, and runs/ corresponding to the thread and run IDs used.

Common Errors

Error	Cause	Fix
`StorageError::Io`	Permission denied on the data directory	Ensure the process has read/write access to the path
`StorageError::Io` with empty ID	Thread or run ID contains invalid characters (`/`, `\`, `..`)	Use simple alphanumeric or UUID-style IDs
Missing data after restart	Using a relative path that resolved differently	Use an absolute path

crates/awaken-stores/src/file.rs – FileStore implementation with filesystem layout details.

Key Files

crates/awaken-stores/Cargo.toml – feature flag definition
crates/awaken-stores/src/file.rs – FileStore
crates/awaken-stores/src/lib.rs – conditional re-export

Keyboard shortcuts

Awaken