All chapters
  1. Start hereMemory is what you keep. A checkpoint is where you stopped
  2. Memory · 1The stateless request: why anything has to be stored at all
  3. Memory · 2Five kinds of memory: working, episodic, semantic, procedural and preference
  4. Memory · 3Conversation history, summaries, retrieval and durable facts
  5. Memory · 4Files as memory in coding agents: instructions, journals, artifacts and checkpoints
  6. Memory · 5Database stores: tables, JSON, documents, objects and vectors
  7. State · 6Run identity: run_id, thread_id, trace_id, correlation_id and task_id
  8. State · 7State machines, checkpoints, event sourcing and where replay must stop
  9. State · 8Failure and resume: idempotency keys, retry policy and the exactly-once illusion
  10. State · 9The transactional outbox: side effects, compensation and deduplication
  11. Policy · 10Memory write policy: extraction, confidence, provenance, expiry and deletion
  12. Policy · 11Retrieval and ranking: relevance, recency, salience and scope
  13. Policy · 12Shared memory between agents: consistency, isolation, ownership and races
  14. Policy · 13Security: tenant separation, personal data, secrets, consent and retention
  15. Practice · 14Evaluation: memory correctness, stale facts, contamination and recovery tests
  16. Practice · 15Frameworks and standards: what each one stores for you
  17. Practice · 16The insurance lab: one run that fails, resumes and remembers, end to end
  18. Practice · 17Advanced: migration, conflict resolution, forgetting, summary drift and disaster recovery
  19. ReferenceGlossary
  20. AboutAbout this site and its sources
Policy · 12

Shared memory between agents: consistency, isolation, ownership and races

Three agents read and write the same record. Lost updates, stale reads, who owns which field, and the version check that turns a silent overwrite into a visible conflict.

What you will understand
Three races
Lost update, stale read and write skew: how two correct agents produce a wrong record.
Three rules
Last write wins, a version check, or append-only, and what each one does with a conflict.
Ownership
Why the cheapest fix is often to decide who owns which field.

In the multi-agent version of the example, three agents work on submission SUB-1004. The intake agent turns the broker's email into the submission. The assessment agent fetches the roof assessment and adds what the provider says. The underwriting agent reads both and writes a recommendation. They share one record for the submission, a shared working file that each of them reads and updates.

At 10:02:00 the intake agent reads the record to correct the floor area, which the broker has just restated as 21,500 sq ft. At 10:02:01 the assessment agent reads the same record, adds the provider's roof age of 22 years with evidence EV-ROOF-0412, and writes it back. At 10:02:03 the intake agent writes its copy back: the corrected floor area, and every other field as it was when it read them, which means without the provider's roof age.

The record now says nothing about the provider. The underwriting agent reads it, sees only the application's 9 years, and the rule R-ROOF-03, which fires when the two ages differ by more than 5 years, never fires. A conflict that should have gone to a senior underwriter has disappeared. Each agent did its job. No error was raised. This is case UW-M10, one of this site's own cases.

The agent here is a scripted stand-in, so the results on this page show how the mechanism works, not how good any model is.

Shared memory and the word "race"#

Shared memory is a record that more than one agent reads and writes. For example, the shared submission record of SUB-1004, read and written by the intake agent and the assessment agent.

A race condition is a bug whose result depends on the timing of two actors. For example, the result of UW-M10 depends on whether the intake agent writes before or after the assessment agent: one order keeps the roof age, the other loses it.

This page is about shared memory in that ordinary engineering sense: data several writers touch. It covers both kinds this site deals with: shared state of one run, such as the record above, and shared long-term memory, such as a semantic memory in scope broker:BRK-017 that two runs might update at once.

What this is not. Messages that agents send to each other, and the protocols for them, belong to agent communication: a2a.sammuthu.com. Deciding which agent runs next, and in what order, is orchestration: orchestrate.sammuthu.com. This page is about the record they share and what happens when two of them write it.

Three races worth naming#

The opening scene is the first of three classic races. Each has a plain description and a name.

A lost update happens when two writers each read a record, change their copy, and write it back; the second write erases the first. That is UW-M10: the intake agent's write erased the assessment agent's roof age.

A stale read happens when a reader acts on a value that has since changed. For example, the underwriting agent reads the record at 10:02:00, before the roof age arrives, and writes a recommendation at 10:02:05 on the strength of the application's 9 years alone.

A write skew happens when two writers each check a condition that is true, then each make a change that is allowed on its own, and the two changes together break the condition. For example, a rule says at least one of two senior underwriters must be on call for escalations. Each one checks that the other is on call, and each signs off. Both checks were true; both writes were allowed; now nobody is on call.

RaceWhat each writer sawWhat went wrongIn the example
Lost updateThe same old versionThe second write replaced the firstProvider's roof age erased
Stale readA version that later changedThe decision used old dataRecommendation without the provider's age
Write skewTwo different rows, each fineThe combination broke a ruleBoth seniors off call

Three rules for a conflict#

The question is what the store does when the second write arrives. There are three common answers. The lab below runs all three on the four events of UW-M10: the intake agent (A) reads, the assessment agent (B) reads, B writes, A writes. Change the rule and the order of events and see the final record. The table below is the runner's output for that order (python run_memory.py --case UW-M10).

RuleFinal recordLostConflict
Last write winsarea_sq_ft 21500; provider_roof_age_years NoneThe provider's roof ageSilent: 0 conflicts
Version checkarea_sq_ft 21500; provider_roof_age_years 22NothingVisible: 1 conflict, 1 retry by the intake agent
Append-onlyarea_sq_ft 21500; provider_roof_age_years 22NothingNone: two events, one fold

Last write wins accepts every write and keeps the latest. It is the default of almost every key-value store and of naive code that writes a whole object back. It never raises an error, and that is its problem: the lost update in UW-M10 is invisible until someone wonders why the roof was never escalated.

A version check, also called optimistic locking, gives the record a version number. A writer says which version it read; the store accepts the write only if the record is still at that version, and otherwise rejects it. The rejected writer reads again, applies its change to the fresh copy, and writes again. In UW-M10 the intake agent read version 1, the assessment agent wrote version 2, and the intake agent's write "based on version 1" is rejected. It re-reads version 2, sets the floor area, and writes version 3 with both changes.

Append-only never updates in place. Each writer adds an event ("roof assessed: 22 years, EV-ROOF-0412", "floor area corrected to 21,500 sq ft"), and the current record is computed by folding the events in order. Two writers cannot overwrite each other because neither overwrites anything. The cost moves to the fold: someone must define what happens when two events touch the same field. That is the same idea as event sourcing on Checkpoints, applied to shared memory.

The diagram shows the version check on the four events, because it is the rule that turns a silent loss into a visible conflict.

Diagram: UW-M10 with a version check · a silent loss becomes a visible conflict

Read top to bottom. Both agents read version 1. The assessment agent writes first and the record moves to version 2. The intake agent's write still says it read version 1, so the store rejects it. The intake agent reads version 2, applies its one change and writes version 3. Both changes survive.

  1. Assessment agent to Shared record: read: gets version 1. The assessment agent reads the record at version 1.
  2. Intake agent to Shared record: read: gets version 1. The intake agent reads the same version a moment later.
  3. Assessment agent to Shared record: write, based on v1: accepted: now v2. The version matches, so the write is accepted and the record moves to version 2 with the provider's roof age.
  4. Shared record to Intake agent: rejected: you read v1, record is v2. The record is no longer at version 1. Under last write wins this write would have erased the roof age. Here it is refused.
  5. Intake agent to Shared record: re-read: gets version 2. The intake agent reads the fresh record, which now holds the provider's roof age.
  6. Intake agent to Shared record: write, based on v2: accepted: now v3. It applies only its own change to the fresh copy. Version 3 holds both the roof age and the corrected floor area.

Read it from top to bottom. Both agents read version 1. The assessment agent writes first and the store moves to version 2. The intake agent's write still says "I read version 1", so the store refuses it. The intake agent reads version 2, applies its one change, and writes version 3. Nothing was lost, and the conflict was seen by the one writer that could fix it.

For a backend engineer. This is the version column that Java persistence layers use for optimistic locking. In plain SQL: the update carries WHERE id = ? AND version = ? and sets version = version + 1; zero rows updated means someone else got there first, and the code must treat that as a conflict, not as success. Agents need the same thing for the same reason. What is different is the writer: a model-driven agent that receives a rejection should re-read and redo its change from the fresh record, not retry the same payload.

Ownership: the cheapest fix#

Version checks handle conflicts. Ownership prevents most of them. Ownership means each field has exactly one writer. For example, the intake agent owns the fields that come from the broker's email, the assessment agent owns the fields that come from the provider, the underwriting agent owns the recommendation, and only a person writes the decision.

Field groupOwnerOthers may
Application fields (roof_age_years, area_sq_ft, contact)Intake agentRead
Provider fields (provider roof age, EV-ROOF-0412)Assessment agentRead
RecommendationUnderwriting agent, through record_recommendationRead
human_decisionThe underwriterRead; never write

If the intake agent writes only its own fields, and the store applies a write as a change to named fields instead of a whole-record replace, the race in UW-M10 cannot lose the roof age at all: the two agents never write the same field. A version check remains useful as a guard, but conflicts become rare.

Ownership also answers a question the next page needs: when a field is wrong, whose job is it to fix? With ownership there is one answer.

Isolation, in one table#

Inside one relational database, the transaction's isolation level decides which of these races the database itself prevents. Isolation is how far concurrent transactions are kept from seeing each other's partial work. PostgreSQL's documentation (version 18) lists four levels; its default is Read Committed.

PostgreSQL levelLost update in a read-modify-writeWhat the documentation says happens
Read Committed (default)Possible, if the application reads, changes in code and writes the whole rowEach statement sees data committed before it began
Repeatable ReadPrevented: the second update fails"could not serialize access due to concurrent update"; retry the transaction
SerializablePrevented, including write skewA transaction that could break serial order fails; retry it
Read UncommittedAs Read CommittedPostgreSQL's Read Uncommitted behaves like Read Committed

Two cautions. First, isolation works only when both writers' read and write are inside one database transaction. Agents usually read, call a model for seconds, and then write, and a transaction should not be held open across a model call. So in agent systems the version check at write time is the practical form. Second, the shared record may not be in a relational database at all; a document store or a key-value store has its own rules, read in its documentation.

The failure, and the test that catches it#

The failure in UW-M10 has a nasty property: no test that runs the agents one after the other will find it. It appears only when the timing interleaves. The test, therefore, forces the interleaving.

  1. Start from version 1 of the shared record.
  2. Let agent A (intake) read, then agent B (assessment) read.
  3. Let B write, then A write.
  4. Assert that the final record contains both A's field and B's field, or that A received a conflict.

Under last write wins the assertion fails: the provider's roof age is missing. Under a version check A receives a conflict, re-reads and writes version 3, and the assertion passes. The example's tests do exactly this for all three rules. Run the same four steps for every pair of agents that can write the same record.

Framework implementation#

Some agent frameworks give each agent its own state and merge updates through declared rules per field, which is ownership expressed in code. Others give shared stores with or without versions. What a named framework does on a concurrent write is read on Frameworks; assume last write wins until its documentation says otherwise.

A checklist for Monday#

  1. List every record two agents can write. For each, which rule applies today: last write wins, version check, or append-only?
  2. Does any writer replace a whole record when it changed one field?
  3. Does each field have one owner? Write the ownership table down.
  4. What does an agent do when its write is rejected: retry the same payload, or re-read and redo?
  5. Is there a test that forces A-read, B-read, A-write, B-write?
Advanced: choosing between version checks, append-only and merge rules

A version check is simple and catches every lost update, at the cost of retries under contention. When many agents write one hot record, retries pile up and some writers starve. The usual repair is to split the hot record by owner, so that writers stop sharing it.

Append-only removes write conflicts and pushes the problem into the fold. The fold must say what two events on the same field mean: the latest wins, the most trusted source wins, or both are kept as a conflict for a person. That is conflict resolution, the subject of Advanced. Append-only also makes audit free, which matters in a regulated domain: every change has a writer and a time.

Field-level merge rules (each field declares how concurrent updates combine: replace, append to a list, take the maximum) are a middle path. They work well when fields are independent. They fail quietly on write skew, where the invariant spans fields or rows, and only serializable transactions or an explicit check of the invariant at write time catches that.

For long-term memory the same analysis holds with a twist: two runs may write two different semantic memories that contradict each other, with no shared row to conflict on. No locking catches that. A uniqueness rule per scope and subject (one active memory per broker:BRK-017 and roof_age_source) turns the contradiction into a conflict the store can detect.

Advanced: consistency across stores

Consistency, in the sense used here, is whether every reader sees the same, valid state. Inside one database a transaction gives it. Across two stores, for example the relational record and a vector index built from it, there is a window in which one has the new value and the other the old. A reader that combines both in that window sees a state that never existed.

Two habits help. Treat one store as the source of truth for each field and the others as derived copies with a known lag. And put the version of the source row into the derived copy, so that a reader can detect that the copy is behind. The same idea lets the outbox on Outbox keep a message and a row consistent.

In one breath#

When several agents write one record, two correct agents can produce a wrong record: a lost update, a stale read, or a write skew. Last write wins hides the conflict; a version check turns it into a rejection that the writer resolves by re-reading; append-only removes the overwrite and moves the question into the fold. Decide who owns each field first, and most conflicts never happen.

The same idea for a coding agent: two agents editing the same file in one working copy is a lost update waiting to happen; separate branches or worktrees are ownership, and a merge conflict is a version check that a person resolves.

The record now survives concurrent writers. What it holds is still a database of things people said, with everything that makes such a database sensitive. Security.