Copy-on-Write

Every write in SenseLab creates a new version of an entry. The previous version is preserved as superseded. Nothing an agent learned is ever overwritten. This is what the rest of the loop stands on. A decision trace can cite the exact version an agent read, so an outcome is credited to what the agent actually saw rather than to whatever the entry says today. A fix that makes things worse can be rolled back to the version before it. And two agents that disagree both keep their position, with their names on it, instead of one silently winning.

How It Works

When you write to a key that already exists:

The current version is marked as superseded
A new version is created with an incremented version number
The new version becomes the current version

# Version 1 is created
mem.write("svc", "config", {"pool_size": 5})

# Version 2 is created; version 1 is superseded
mem.write("svc", "config", {"pool_size": 10})

# Version 3 is created; version 2 is superseded
mem.write("svc", "config", {"pool_size": 20})

Reading always returns the current (latest) version:

entry = mem.read("svc", "config")
print(entry.version)  # 3
print(entry.value)    # {"pool_size": 20}

Viewing History

history() returns every version of one key, oldest first. Each version is a full snapshot, not a delta, so you can read any past state directly:

for entry in mem.history("svc", "config"):
    print(f"v{entry.version}: {entry.value} (confidence {entry.confidence})")

It also takes since and until, which is how you reconstruct what an agent knew at the moment it decided something. To see all versions across an entity rather than one key, use list():

all_versions = mem.list("svc", include_superseded=True)

On the dashboard, the same history is the Event Log of the agent’s Git Repository section — see Learning as Git.

Comparing Versions

Because every version is kept, SenseLab can show exactly which fields changed rather than just that something did. diff() returns structural, field-level changes addressed by RFC 6901 JSON Pointer paths:

# Diff a specific version against the current one.
# Omit old_version to compare the two most recent versions.
result = mem.diff("svc", "config", old_version=1)

for change in result["field_changes"]:
    print(f"{change['operation']} {change['path']}: "
          f"{change['old_value']} → {change['new_value']}")

replace /pool_size: 5 → 20

Each change carries a path, an operation of add, remove, or replace, and the old and new values. The surrounding result also reports diff_type (added, modified, or deleted) and the two versions’ confidence. This works on nested dicts, lists, and scalars, so a change buried deep in a config object is reported at its exact path instead of as a wholesale replacement of the value.

Version Retention

Every version is kept. Superseding a key never overwrites the previous value — it marks it as no longer current and stores the new one alongside it, so the full chain stays queryable through history() for as long as the entry exists. Outcomes are versions too: when a committed outcome moves an entry’s confidence, the entry gets a new version with the new confidence and the old one is superseded, so the trust an entry has earned over time is as traceable as its value.

Conflict Handling

When two agents write to the same key concurrently, the conflict_policy determines behavior:

Policy	Behavior
`LAST_WRITE_WINS`	Default. The latest write takes precedence.
`RAISE`	Raises `StaleWriteError` if another agent advanced the version since your last read.

from amfs import ConflictPolicy

mem = AgentMemory(
    agent_id="my-agent",
    adapter=adapter,
    conflict_policy=ConflictPolicy.RAISE,
)

You can also provide a custom conflict resolver:

def resolve(existing, incoming, value):
    # Merge logic here
    return {**existing.value, **value}

mem = AgentMemory(
    agent_id="my-agent",
    adapter=adapter,
    on_conflict=resolve,
)

For changes that need review before they reach everyone, write them on a branch and open a pull request instead of resolving the conflict at write time.

Why copy-on-write

Attribution — An outcome is credited to the version the agent read, so trust moves on the right thing.
Reversibility — A fix, a merge or a bad write can be undone by rolling back; nothing has to be reconstructed.
Audit — Months later, history() and the decision trace still answer who believed what, at what confidence, and what followed.
Training data — The record of what was known at each decision, as it was then, is what a model can be trained on. See ML Layer.

Product

Getting Started

Guides

Self-Hosting

Core Concepts

Pro Features

How It Works

Viewing History

Comparing Versions

Version Retention

Conflict Handling

Why copy-on-write

​How It Works

​Viewing History

​Comparing Versions

​Version Retention

​Conflict Handling

​Why copy-on-write

How It Works

Viewing History

Comparing Versions

Version Retention

Conflict Handling

Why copy-on-write