How do you maintain data consistency during shared-memory migrations in multi-agent systems?

Maintaining data consistency during a shared-memory migration means ensuring that agents see authoritative, correctly versioned information even while old and new storage formats coexist. The main risk is not just a failed conversion: agents may continue writing to the old format, overwrite a newer update, or retrieve stale indexed data.

Beginner-friendly example

An API-testing platform has requirements, generation, and review agents that share a durable memory record for endpoint authentication.

• Old memory: auth="OAuth2".
• New memory: auth={"scheme":"OAuth2","scopes":["pay:write"]}.

While 5,000 records are being migrated, the requirements agent may update one endpoint's scopes. A migration worker must not overwrite that new information using the old snapshot.

Choose an authoritative write path → Capture revisions → Backfill conditionally → Reconcile ongoing updates → Verify reads and indexes → Switch consumers

Numerical example: a race condition

Consider record m42:

1. At 10:00, a migrator reads revision 7, where the requirement contains only OAuth2.
2. At 10:01, the requirements agent updates the record to revision 8, adding a verified pay:write scope.
3. At 10:02, the migrator attempts to write a converted copy based on revision 7.
4. An unsafe unconditional write could overwrite revision 8 and lose the new scope.
5. With compare-and-swap, the migration updates only if the current revision is still 7. Because it is now 8, the update is rejected; the migrator rereads and transforms revision 8 instead.

In a database, this can be implemented with a conditional write such as UPDATE ... WHERE id = ... AND revision = 7, checking that exactly one row changed. A zero-row result means another writer changed the record or it was removed.

Techniques for consistent migration

1. One authoritative source: Define where accepted writes live throughout the transition. Avoid treating two independently writable copies as equally authoritative.
2. Revisioned writes: Use optimistic concurrency checks, transactions, or carefully scoped locks to protect updates from being overwritten.
3. Snapshot plus change capture: Backfill a consistent snapshot, then apply changes made after that snapshot through a durable change log or controlled event stream.
4. Controlled dual writes: If old and new stores both need updates, coordinate them using a transaction when supported or a transactional outbox plus retries and reconciliation. Two unrelated writes cannot be assumed atomic.
5. Idempotent migration: Give each converted record a stable ID, source revision, and migration version so retries do not duplicate or regress data.
6. Version-aware reads: During transition, read the new representation only when it has a validated revision; otherwise use a known-good authoritative source.
7. Index and cache reconciliation: Refresh vector indexes and invalidate stale caches after committed updates; track which source revision each index entry represents.
8. Repair and rollback plans: Preserve original versions, record mismatches, and stop promotion on unexplained divergence.
9. Tenant isolation: Retain ownership and access-control metadata through every transform, including embeddings and caches.

Reconciliation example

Suppose 10,000 records must be migrated and 9,900 match the authoritative source after backfill. The apparent match rate is 9,900 / 10,000 = 99%, leaving 100 mismatches.

The correct next action is not to declare success based on 99%. Classify the 100 discrepancies: newer writes, invalid source data, transform errors, or missing index updates. Set acceptance thresholds based on impact; zero mismatched authorization records may be required before switching security-sensitive consumers.

What should consistency checks compare?

• Stable record ID, tenant, and source provenance.
• Logical content, including required scopes—not just serialized JSON equality.
• Current revision and last applied source event.
• Required fields and explicit unknown values.
• Corresponding cache and search-index revision.

For semantically equivalent old and new shapes, use a canonical comparison rather than comparing raw strings.

LangGraph and Celery considerations

In LangGraph, a checkpoint may reference a shared-memory revision. On resumption, check whether the referenced record is still valid or whether the workflow must reload authoritative data. Checkpoint compatibility alone does not guarantee current memory consistency.

With Celery, backfill and change-application tasks may be retried, redelivered, or executed out of order. Carry record revisions and stable event IDs, apply changes conditionally, and avoid allowing an older retry to undo a newer update.

Difference from related lessons

• Shared-state consistency covers normal concurrent agent updates.
• Shared-memory schema migration covers changing a durable record's format.
• Consistency during migration covers keeping old/new data, live writes, caches, and indexes synchronized while that format change is underway.

In short

Use a single authority, revision-checked writes, durable change capture, idempotent backfills, and semantic reconciliation. Cut over only after validating that agents retrieve correct, current, tenant-isolated information.