Skip to main content
Every write in AMFS creates a new version of an entry. The previous version is preserved as superseded. This means you never lose history — every change is traceable.

​
How It Works

When you write to a key that already exists:
  1. The current version is marked as superseded
  2. A new version is created with an incremented version number
  3. 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

Use list() with include_superseded=True to see all versions: 
all_versions = mem.list("svc", include_superseded=True)
for entry in all_versions:
    print(f"v{entry.version}: {entry.value}")
Or use the CLI: 
amfs inspect diff svc config

​
On-Disk Layout (Filesystem Adapter)

The filesystem adapter stores each version as a separate JSON file: 
.amfs/default/checkout-service/retry-pattern/
├── v001_superseded.json
├── v002_superseded.json
└── v003_current.json
  • _current.json — the active version
  • _superseded.json — previous versions, kept for history
Writes use atomic rename (os.rename()) with advisory file locking (flock()) to prevent corruption from concurrent writes.

​
Conflict Handling

When two agents write to the same key concurrently, the conflict_policy determines behavior:
PolicyBehavior
LAST_WRITE_WINSDefault. The latest write takes precedence.
RAISERaises StaleWriteError if another agent advanced the version since your last read.
from amfs_core.models import ConflictPolicy

mem = AgentMemory(
    agent_id="my-agent",
    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",
    on_conflict=resolve,
)

​
Why CoW?

  • Auditability — Every change is recorded. You can always trace how knowledge evolved.
  • Safety — No data is lost. Mistakes can be identified by comparing versions.
  • Outcome tracking — Outcomes create new versions with updated confidence scores, preserving the score history.