Shared Memory Across Agent Ensembles: Consistency Models for Distributed State

May 15, 2026

When agent ensembles operate as independent services on a network, they occasionally need to share state. The question is not whether to share state — it is how to share it without creating the coordination problems that shared mutable state always creates in distributed systems.

The consistency spectrum

Not all shared state needs the same consistency guarantees:

Inventory notes are advisory. Eventual consistency is fine.
Room assignments are exclusive. This needs distributed locks or optimistic locking.
Configuration preferences are rarely updated. Eventual consistency with version tracking works well.

SharedMemory with configurable consistency

AgentEnsemble v3.0.0 introduces SharedMemory with per-scope consistency selection:

Model	Behavior	Use case
`EVENTUAL`	Last-write-wins, no coordination	Context, preferences, notes
`OPTIMISTIC`	Version-checked writes, retry on conflict	Counters, shared documents
`LOCKED`	Distributed lock before each read/write	Room assignments, exclusive resources

Different scopes can use different models:

SharedMemory inventory = SharedMemory.builder()
    .store(MemoryStore.inMemory())
    .consistency(Consistency.EVENTUAL)
    .build();

SharedMemory rooms = SharedMemory.builder()
    .store(MemoryStore.inMemory())
    .consistency(Consistency.LOCKED)
    .build();

The design principle

The useful insight is that shared state in agent networks is not monolithic. Different categories of state need different consistency guarantees, and forcing a single model is either too expensive or too weak.

The consistency model is a property of the data, not a property of the system. Choose it based on what happens when two ensembles access the same state concurrently.

Shared memory is part of AgentEnsemble. The shared memory guide covers the full API including consistency models and network configuration.