Agentfs
Files and Metadata
Files and Metadata in AgentFS. Local agent filesystem with contexts, registry, permissions, metadata hooks, sync, watchers, and atomic writes.
Purpose
Local agent filesystem with contexts, registry, permissions, metadata hooks, sync, watchers, and atomic writes.
This page follows the real source shape for Agentfs and explains the workflow a developer is likely to use first.
Storage contract
Document persistence format, integrity checks, read/write ordering, idempotency, compaction or repair behavior, and how callers recover from partial failures. This section should answer what data is durable and what can be reconstructed.
Primary types to know
AgentContext— local/agentfs/src/agent.rsAgentContext— local/agentfs/src/agent_refactored.rsAgentFS— local/agentfs/src/fs.rsAgentFS— local/agentfs/src/fs_refactored.rsAgentFSConfig— local/agentfs/src/config.rsAgentPermission— local/agentfs/src/permissions.rsAgentPermission— local/agentfs/src/permissions_refactored.rsAgentRegistry— local/agentfs/src/agent.rsAgentRegistry— local/agentfs/src/agent_refactored.rsConflictInfo— local/agentfs/src/sync_refactored.rsFsckReport— local/agentfs/src/fs.rsFsMetrics— local/agentfs/src/fs.rs
Example shape
use agentfs::{AgentFS, AgentFSConfig, AtomicMode};
use std::sync::Arc;
use weave_identity::{Ed25519Adapter, Identity};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// AgentFS pairs a real filesystem root with an Identity-aware adapter.
// Atomic mode controls how partial writes are committed (Rename vs Direct).
let dir = tempfile::tempdir()?;
let cfg = AgentFSConfig::new()
.with_atomic_mode(AtomicMode::Rename)
.with_follow_links(false);
let adapter: Arc<dyn weave_identity::WeaveIdentityAdapter> = Arc::new(Ed25519Adapter::new());
let agent = Identity::agent_from_public_key(vec![0u8; 32], Some("agentfs-demo"))?;
let org = Identity::ao_from_public_key(vec![1u8; 32], "demo-org")?;
let fs = AgentFS::new(dir.path().into(), cfg, agent, org, adapter).await?;
// Files and metadata move through the same path namespace.
fs.mkdir("/notes", false).await?;
fs.write_file("/notes/today.md", b"# today").await?;
fs.put_metadata("/notes/today.md", serde_json::json!({ "tags": ["draft"] })).await?;
let stored = fs.get_metadata("/notes/today.md").await?;
let bytes = fs.read_file("/notes/today.md").await?;
println!("metadata={:?} content_bytes={}", stored, bytes.len());
Ok(())
}