Memory Consistency Model Selector
Overview
When Agent A writes a fact to shared memory, when does Agent B see it? Ch4
names this the memory consistency problem, and getting it wrong produces agents
that contradict each other, overwrite each other's conclusions, or act on stale
information. This is CAP — the classic consistency/availability trade-off —
applied per coordination operation to shared agent memory, not decided once
globally. Consistency is chosen per operation because most workflows mix
safety-critical decision points with tolerant background work.
Four consistency models, each with a characteristic profile:
- strong (linearizable): every agent sees the latest write before any
proceeds. A synchronization barrier after every write — expensive, but
required when agents act on shared authoritative state (locks, budgets,
inventory) or make safety-critical irreversible decisions. The chapter's
example: a drug-interaction finding every agent must see before recommending
treatment.
- causal: causally-related writes are ordered; unrelated updates may lag.
If A's conclusion depends on B's finding, any reader of A also sees B. The
practical default for collaborating agents.
- read_your_writes: an agent always sees its own writes; other agents'
writes may arrive later. Session memory for a single agent's continuity.
- eventual: cheapest; all agents converge eventually, but not when. Fine
when no single fact is safety-critical and a final synthesis reconciles
disagreement (background enrichment, literature accumulation).
The selector scores each model across the operation's requirement axes and
recommends one, surfacing escalate_to_strong when the default is not strong
but the operation touches authoritative state — the chapter's rule: default
to causal, escalate the irreversible decision points to strong.
The cache-divergence helper makes the failure concrete. Ch4's cache-sharing
section warns that without a protocol, Agent B acts on a cached read that a
newer committed write already superseded. detect_cache_divergence flags
exactly that: any cached snapshot older than the latest committed write on the
same key.
When to Use
- Designing shared memory for a multi-agent system with concurrent writers
- Justifying a consistency choice for one coordination operation in a design doc
- Auditing a handoff where an agent may be acting on a stale cached value
- Deciding whether a decision point needs a strong-consistency barrier
Phrases: "consistency model", "linearizable vs eventual", "causal consistency",
"read your writes", "stale cache", "multi-agent memory coordination", "when does
Agent B see Agent A's write", "CAP for agent memory".
When NOT to Use
- Single-agent / stateless systems. No cross-agent coordination means no
consistency problem to solve.
- Picking a datastore product. This selects the consistency model, not
Redis-vs-etcd-vs-Postgres. Product choice is downstream.
- A platform-mandated model. If the framework fixes the consistency
guarantee, adopt it; the scoring is moot.
- A single global decision. The chapter's point is per-operation choice; do
not collapse a whole system to one model to "keep it simple" (see the
rationalizations).
Process
| Step |
Input |
Action |
Output |
Verification |
| 1 |
operation requirements (5 weights 0..3) |
lib.score_models(op) |
[(model, score), ...] sorted desc |
weights * fitness, descending |
| 2 |
same |
lib.recommend_model(op) |
{recommended, scores, rationale, profile, escalate_to_strong} |
strong on authoritative/conflict, eventual on staleness, causal on collaboration, ryw on self-session |
| 3 |
committed writes + per-agent cached reads |
lib.detect_cache_divergence(writes, snaps) |
list of {agent, key, cached_at, latest_write_at, staleness_gap} |
stale snapshot flagged; current snapshot clean |
CLI: recommend, score, cache-check, scenario (shared-budget-lock /
background-enrichment / collaborative-research / session-assistant),
benchmark.
Rationalizations
| Agent rationalization |
Documented rebuttal |
| "Just use strong consistency everywhere, it's the safe default." |
Strong pays a synchronization barrier after every write. On a literature-accumulation or background-enrichment operation that cost buys nothing — no single fact is safety-critical. Ch4: default to causal, escalate to strong only for irreversible decision points. Blanket-strong is the availability tax the per-operation choice exists to avoid. |
| "Eventual is cheapest, use it globally." |
Eventual on a shared budget or inventory lock means two agents read different versions and both spend the same money. escalate_to_strong fires precisely because the workflow default and the individual authoritative decision point need different models. |
| "One consistency model per system keeps it simple." |
The chapter is explicit that consistency is chosen per operation: a pull-request review (strong) versus feature-branch tests (eventual) versus a merge queue (causal) coexist in one repo. Collapsing to one model either over-pays everywhere or under-protects the safety-critical points. |
| "Cache staleness is an edge case, skip the check." |
Ch4's cache-sharing section names it as the concrete failure surface: without a protocol, Agent B acts on a superseded cached read and produces a contradictory result. detect_cache_divergence is the cheap deterministic guard; a divergent decision downstream is not cheap. |
| "Causal is basically read-your-writes, they're interchangeable." |
No. Read-your-writes guarantees an agent sees only its OWN writes; causal orders writes across agents that are causally linked. A collaboration operation where A builds on B needs causal; a single agent's session continuity needs read-your-writes. The scoring separates them so the wrong one is not chosen by habit. |
Red Flags
- All five requirement weights set to 3. You have not prioritized the
operation. Re-interview: if every axis is critical, the selector degenerates
to raw fitness averages.
- Recommended = eventual but the operation touches a budget/lock. Mismatch:
authoritative state cannot ride on eventual consistency. Check
escalate_to_strong.
- One consistency model chosen for the entire system. The chapter mandates
per-operation choice; a single global model is a design smell.
- Cache-check returns divergences and they are ignored. Each stale agent is
a contradictory-decision risk. Add a cache-sharing protocol (broadcast,
pub-sub, or request-grant per Ch4) or force a re-read before the handoff.
Non-Negotiable Verification
- Run the benchmark battery.
python cli.py benchmark must report 11/11:
- strong wins on shared-authoritative-state and on conflict-intolerance
- eventual wins on high staleness budget, causal on collaboration,
read_your_writes on self-session-only
- zero requirements score all models 0; all four are scored, descending
- cache-check flags a stale read with the correct staleness gap and stays
clean when the cache is current
escalate_to_strong fires when causal is the default but authoritative
state is present- the requirement-axis set and the four-model set have not drifted
- Run a scenario.
python cli.py scenario shared-budget-lock recommends
strong; python cli.py scenario background-enrichment recommends eventual.
- Verify CLI help.
python cli.py --help exits 0 and prints this SKILL.md
description (so any harness can discover the skill from --help).
Security Posture
- Prompt injection. Inputs are requirement weights and write/snapshot
metadata - pure data scored against fixed fitness tables. Adversarial values
can at most skew the recommendation (e.g. under-weighting authoritative
state to dodge a strong barrier); nothing in the input is executed.
- Data exfiltration. No network calls, no file writes. Write timestamps
and cache snapshots may reveal coordination topology; they stay in-process
and appear only in the stdout report the caller owns.
- Privilege escalation. No shell invocation, no eval, no dynamic import.
The recommendation is advisory: a mis-chosen eventual model on a shared
budget is a correctness/safety hazard, which is why
escalate_to_strong
fires - but the actual synchronization barrier is enforced by the memory
store, not by this selector.
Source Attribution
Distilled from Agentic GraphRAG (O'Reilly, by Anthony Alcaraz and Sam Julien) Ch4 — Memory,
sections "Memory consistency models for agent coordination" (the strong /
causal / eventual models and the default-causal-escalate-to-strong rule) and
"Cache sharing in multi-agent systems" (broadcast / pub-sub / request-grant
patterns and the stale-cache failure surface). The read-your-writes model is
the standard session-consistency guarantee from distributed-systems practice,
added as the fourth per-operation option. The consistency/availability framing
is the CAP theorem (Brewer) applied per coordination operation.
1---2name: memory-consistency-model-selector3description: Choose a memory consistency model PER agent-coordination operation — STRONG (linearizable), CAUSAL, READ-YOUR-WRITES, or EVENTUAL — by scoring the operation's requirements (shared authoritative state, conflict intolerance, staleness budget, collaboration, self-session continuity), per Ch4 "Memory consistency models for agent coordination". The chapter's rule: default to causal, escalate to strong only for irreversible decision points. Also flags cache-sharing divergence — an agent acting on a cached read older than a committed write it depends on. Use when designing shared memory for a multi-agent system, justifying a consistency choice, or auditing a stale- cache handoff. NOT for single-agent stateless systems (no coordination), NOT for picking a datastore product (this picks the model, not Redis-vs-etcd), NOT when the platform already mandates a consistency model (just adopt it).4---56# Memory Consistency Model Selector78## Overview910When Agent A writes a fact to shared memory, when does Agent B see it? Ch411names this the memory consistency problem, and getting it wrong produces agents12that contradict each other, overwrite each other's conclusions, or act on stale13information. **This is CAP — the classic consistency/availability trade-off —14applied per coordination operation to shared agent memory, not decided once15globally.** Consistency is chosen per operation because most workflows mix16safety-critical decision points with tolerant background work.1718Four consistency models, each with a characteristic profile:1920- **strong** (linearizable): every agent sees the latest write before any21 proceeds. A synchronization barrier after every write — expensive, but22 required when agents act on shared **authoritative** state (locks, budgets,23 inventory) or make safety-critical irreversible decisions. The chapter's24 example: a drug-interaction finding every agent must see before recommending25 treatment.26- **causal**: causally-related writes are ordered; unrelated updates may lag.27 If A's conclusion depends on B's finding, any reader of A also sees B. The28 practical default for collaborating agents.29- **read_your_writes**: an agent always sees its own writes; other agents'30 writes may arrive later. Session memory for a single agent's continuity.31- **eventual**: cheapest; all agents converge eventually, but not when. Fine32 when no single fact is safety-critical and a final synthesis reconciles33 disagreement (background enrichment, literature accumulation).3435The selector scores each model across the operation's requirement axes and36recommends one, surfacing `escalate_to_strong` when the default is not strong37but the operation touches authoritative state — the chapter's rule: **default38to causal, escalate the irreversible decision points to strong.**3940The cache-divergence helper makes the failure concrete. Ch4's cache-sharing41section warns that without a protocol, Agent B acts on a cached read that a42newer committed write already superseded. `detect_cache_divergence` flags43exactly that: any cached snapshot older than the latest committed write on the44same key.4546## When to Use4748- Designing shared memory for a multi-agent system with concurrent writers49- Justifying a consistency choice for one coordination operation in a design doc50- Auditing a handoff where an agent may be acting on a stale cached value51- Deciding whether a decision point needs a strong-consistency barrier5253Phrases: "consistency model", "linearizable vs eventual", "causal consistency",54"read your writes", "stale cache", "multi-agent memory coordination", "when does55Agent B see Agent A's write", "CAP for agent memory".5657## When NOT to Use5859- **Single-agent / stateless systems.** No cross-agent coordination means no60 consistency problem to solve.61- **Picking a datastore product.** This selects the consistency model, not62 Redis-vs-etcd-vs-Postgres. Product choice is downstream.63- **A platform-mandated model.** If the framework fixes the consistency64 guarantee, adopt it; the scoring is moot.65- **A single global decision.** The chapter's point is per-operation choice; do66 not collapse a whole system to one model to "keep it simple" (see the67 rationalizations).6869## Process7071| Step | Input | Action | Output | Verification |72|------|-------|--------|--------|--------------|73| 1 | operation requirements (5 weights 0..3) | `lib.score_models(op)` | `[(model, score), ...]` sorted desc | weights * fitness, descending |74| 2 | same | `lib.recommend_model(op)` | `{recommended, scores, rationale, profile, escalate_to_strong}` | strong on authoritative/conflict, eventual on staleness, causal on collaboration, ryw on self-session |75| 3 | committed writes + per-agent cached reads | `lib.detect_cache_divergence(writes, snaps)` | list of `{agent, key, cached_at, latest_write_at, staleness_gap}` | stale snapshot flagged; current snapshot clean |7677CLI: `recommend`, `score`, `cache-check`, `scenario` (shared-budget-lock /78background-enrichment / collaborative-research / session-assistant),79`benchmark`.8081## Rationalizations8283| Agent rationalization | Documented rebuttal |84|------------------------|--------------------|85| "Just use strong consistency everywhere, it's the safe default." | Strong pays a synchronization barrier after every write. On a literature-accumulation or background-enrichment operation that cost buys nothing — no single fact is safety-critical. Ch4: default to causal, escalate to strong only for irreversible decision points. Blanket-strong is the availability tax the per-operation choice exists to avoid. |86| "Eventual is cheapest, use it globally." | Eventual on a shared budget or inventory lock means two agents read different versions and both spend the same money. `escalate_to_strong` fires precisely because the workflow default and the individual authoritative decision point need different models. |87| "One consistency model per system keeps it simple." | The chapter is explicit that consistency is chosen per operation: a pull-request review (strong) versus feature-branch tests (eventual) versus a merge queue (causal) coexist in one repo. Collapsing to one model either over-pays everywhere or under-protects the safety-critical points. |88| "Cache staleness is an edge case, skip the check." | Ch4's cache-sharing section names it as the concrete failure surface: without a protocol, Agent B acts on a superseded cached read and produces a contradictory result. `detect_cache_divergence` is the cheap deterministic guard; a divergent decision downstream is not cheap. |89| "Causal is basically read-your-writes, they're interchangeable." | No. Read-your-writes guarantees an agent sees only its OWN writes; causal orders writes across agents that are causally linked. A collaboration operation where A builds on B needs causal; a single agent's session continuity needs read-your-writes. The scoring separates them so the wrong one is not chosen by habit. |9091## Red Flags9293- **All five requirement weights set to 3.** You have not prioritized the94 operation. Re-interview: if every axis is critical, the selector degenerates95 to raw fitness averages.96- **Recommended = eventual but the operation touches a budget/lock.** Mismatch:97 authoritative state cannot ride on eventual consistency. Check `escalate_to_strong`.98- **One consistency model chosen for the entire system.** The chapter mandates99 per-operation choice; a single global model is a design smell.100- **Cache-check returns divergences and they are ignored.** Each stale agent is101 a contradictory-decision risk. Add a cache-sharing protocol (broadcast,102 pub-sub, or request-grant per Ch4) or force a re-read before the handoff.103104## Non-Negotiable Verification1051061. **Run the benchmark battery.** `python cli.py benchmark` must report 11/11:107 - strong wins on shared-authoritative-state and on conflict-intolerance108 - eventual wins on high staleness budget, causal on collaboration,109 read_your_writes on self-session-only110 - zero requirements score all models 0; all four are scored, descending111 - cache-check flags a stale read with the correct staleness gap and stays112 clean when the cache is current113 - `escalate_to_strong` fires when causal is the default but authoritative114 state is present115 - the requirement-axis set and the four-model set have not drifted1162. **Run a scenario.** `python cli.py scenario shared-budget-lock` recommends117 strong; `python cli.py scenario background-enrichment` recommends eventual.1183. **Verify CLI help.** `python cli.py --help` exits 0 and prints this SKILL.md119 description (so any harness can discover the skill from --help).120121## Security Posture122123- **Prompt injection.** Inputs are requirement weights and write/snapshot124 metadata - pure data scored against fixed fitness tables. Adversarial values125 can at most skew the recommendation (e.g. under-weighting authoritative126 state to dodge a strong barrier); nothing in the input is executed.127- **Data exfiltration.** No network calls, no file writes. Write timestamps128 and cache snapshots may reveal coordination topology; they stay in-process129 and appear only in the stdout report the caller owns.130- **Privilege escalation.** No shell invocation, no eval, no dynamic import.131 The recommendation is advisory: a mis-chosen eventual model on a shared132 budget is a correctness/safety hazard, which is why `escalate_to_strong`133 fires - but the actual synchronization barrier is enforced by the memory134 store, not by this selector.135136## Source Attribution137138Distilled from *Agentic GraphRAG* (O'Reilly, by Anthony Alcaraz and Sam Julien) Ch4 — Memory,139sections "Memory consistency models for agent coordination" (the strong /140causal / eventual models and the default-causal-escalate-to-strong rule) and141"Cache sharing in multi-agent systems" (broadcast / pub-sub / request-grant142patterns and the stale-cache failure surface). The read-your-writes model is143the standard session-consistency guarantee from distributed-systems practice,144added as the fourth per-operation option. The consistency/availability framing145is the CAP theorem (Brewer) applied per coordination operation.
AnthonyAlcaraz