State Fabric is FunctionFly's durable state management layer for distributed AI applications. It provides a consistent, fault-tolerant state store that enables agents, pipelines, and long-running workloads to maintain context across restarts, failures, and scaling events without external databases or caching services.

Most serverless platforms treat every function invocation as a blank slate. When your function finishes, its memory is gone. For a simple API endpoint this is fine. For an AI agent that needs to remember a 40-turn conversation, track the progress of a multi-step data pipeline, or coordinate with other agents over several minutes, it is a dealbreaker. Developers end up bolting on Redis, Postgres, or DynamoDB to solve a problem that the platform should handle natively.

State Fabric solves this by making durable state a first-class primitive in every Compute Capsule.

Why State Matters for AI

AI workloads are inherently stateful. Consider a few examples:

  • A customer support agent needs the full conversation history to generate contextually relevant responses
  • A data pipeline processing millions of records needs to track which batches have been ingested, transformed, and loaded
  • A multi-agent system where a planner agent delegates subtasks to specialist agents needs to track the status of each subtask
  • A code generation agent that iterates on a solution needs to remember previous attempts and why they failed

In each case, losing state means losing work. If a pipeline crashes halfway through, you either reprocess everything from the start or manually figure out where it left off. If an agent loses its conversation history, the user has to repeat themselves. These are not edge cases. They are the normal operating conditions of production AI systems.

State Fabric eliminates this entire class of problems by persisting state automatically and making it available on the next invocation, even if that invocation runs on a different machine in a different availability zone.

Core Primitives

State Fabric exposes three core primitives through the SDK:

Key-Value Store

The simplest primitive. Store and retrieve values by string key with strong consistency guarantees:

typescript 
// Write
await ctx.state.set("user:1234:preferences", {
  theme: "dark",
  language: "en",
  notifications: true,
});

// Read
const prefs = await ctx.state.get("user:1234:preferences");

// Delete
await ctx.state.delete("user:1234:preferences");

Keys are scoped to your Capsule by default. You can optionally set a TTL for automatic expiration:

typescript 
// Expire after 1 hour
await ctx.state.set("session:abc", sessionData, { ttl: 3600 });

Atomic Counters

For distributed coordination, atomic counters provide lock-free increment and decrement operations:

typescript 
await ctx.state.incr("rate-limit:api-key-xyz");
const count = await ctx.state.get("rate-limit:api-key-xyz");
if (count > 100) {
  throw new RateLimitError("Too many requests");
}

Atomic counters are useful for rate limiting, progress tracking, distributed voting, and any scenario where multiple Capsules need to update a shared value without conflicts.

Durable Queues

State Fabric includes a built-in durable queue for fan-out and work distribution:

typescript 
// Producer: enqueue tasks
await ctx.state.enqueue("task-queue", {
  type: "summarize",
  documentId: "doc-789",
  priority: "high",
});

// Consumer: dequeue and process
const task = await ctx.state.dequeue("task-queue");
if (task) {
  await processTask(task);
  await ctx.state.ack("task-queue", task.id);
}

Queues are persistent and support at-least-once delivery. If a consumer crashes before acknowledging a task, it is automatically redelivered to another consumer after a configurable timeout.

Consistency Model

State Fabric uses a leader-follower replication model with Raft consensus for write operations. This means:

  • Writes are linearizable: When you call set(), the write is acknowledged only after a majority of replicas confirm it. Subsequent reads from any replica will see the value.
  • Reads are consistent by default: Reads are served from the leader to guarantee you see the latest write. For read-heavy workloads, you can opt into eventually consistent reads for lower latency.
  • Conflict resolution is automatic: There are no merge functions or vector clocks to manage. The last write wins for key-value pairs, and atomic operations are serialized by the consensus protocol.

This model is the right tradeoff for most AI workloads. Strong consistency for writes prevents data corruption, while the option to relax read consistency allows you to optimize for throughput when stale reads are acceptable.

Fault Tolerance

State Fabric is designed to survive infrastructure failures without data loss:

  • Automatic checkpointing: Every state mutation in a Compute Capsule is checkpointed to durable storage. If the Capsule crashes, it resumes from the last checkpoint on a healthy machine.
  • Cross-zone replication: State is replicated across at least three availability zones. A single zone failure does not affect availability or durability.
  • Point-in-time recovery: State Fabric retains a 7-day history of state changes. You can roll back any key to its value at a specific point in time, which is invaluable for debugging and incident recovery.
typescript 
// Roll back a key to its value 2 hours ago
const twoHoursAgo = new Date(Date.now() - 2 * 60 * 60 * 1000);
const oldValue = await ctx.state.getAt("config:feature-flags", twoHoursAgo);

Performance Characteristics

State Fabric is optimized for the access patterns typical of AI workloads:

  • Latency: Sub-millisecond reads from the local replica, 2-5ms for linearizable writes
  • Throughput: Each Capsule can perform up to 10,000 state operations per second
  • Storage: Individual values can be up to 1MB. Total state per Capsule is 10GB on the free tier and 100GB on paid plans
  • Key size: Keys can be up to 256 bytes, supporting hierarchical naming conventions like agent:session:1234:messages

For workloads that exceed these limits, we recommend sharding across multiple Capsules or using the State Fabric batch API for bulk operations.

Integration with Compute Capsules

State Fabric is tightly integrated with Compute Capsules. State is scoped to a Capsule by default, but you can share state across Capsules using explicit namespaces:

typescript 
// Shared namespace for multi-agent coordination
const shared = ctx.state.namespace("shared:project-abc");
await shared.set("status", "in-progress");

// Another Capsule can read it
const status = await otherCtx.state.namespace("shared:project-abc").get("status");

This makes it straightforward to build multi-agent systems where agents need to coordinate through shared state without an external message broker or database.

When to Use State Fabric vs. External Databases

State Fabric is designed for operational state: session data, task queues, rate limits, feature flags, and coordination primitives. It is not a replacement for a general-purpose database.

Use State Fabric when:

  • You need sub-millisecond state access within a Capsule
  • State lifetime is tied to the Capsule or session lifetime
  • You need atomic operations or durable queues without external dependencies
  • You want automatic checkpointing and fault tolerance

Use an external database (Postgres, DynamoDB, etc.) when:

  • You need complex queries, joins, or aggregations
  • Data must outlive the Capsule indefinitely
  • You need to share data with systems outside FunctionFly
  • Your dataset exceeds 100GB

In practice, most applications use both: State Fabric for fast operational state and an external database for long-term storage and analytics.

Getting Started

State Fabric requires no configuration. Every Compute Capsule has access to it through the SDK context:

typescript 
import { defineCapsule } from "@functionfly/sdk";

export default defineCapsule({
  name: "stateful-agent",
  async handler(ctx) {
    // State Fabric is available immediately
    const count = await ctx.state.incr("invocations");
    console.log(`This Capsule has been invoked ${count} times`);
    return { count };
  },
});

For the full API reference, see the State Fabric documentation. For a practical example, read our tutorial on Building Your First AI Agent, which uses State Fabric for conversation memory.