A new durable fact
Store content with its source. Add an entity and attribute when the fact occupies a stable slot such as appointment day or shipping city.
content + source → active memoryContextDB Memory Evolution · Cloud Alpha
Your agent's memory should know when the customer changed their mind.
Apply ADD, UPDATE, DELETE, or NOOP as one explicit memory operation. Recall the current fact, inspect how it changed, and fail CI if an old memory returns.
The direct answer: Memory Evolution is ContextDB's
state machine for changing factual agent memory. ADD stores a new fact.
UPDATE corrects a known fact and records lineage. DELETE removes a target
or current slot. NOOP records that nothing should change.
The problem
Append-only memory turns yesterday's truth into tomorrow's mistake.
A caller says Thursday works. Later, they correct it to Friday. If your memory layer stores both statements as unrelated vectors, retrieval can return either one. The model then has to guess which fact is current.
ContextDB makes the change explicit before retrieval. One operation closes the old fact, writes or removes the current fact, advances the project memory version when state changes, and appends the related audit event.
Thursday is active
mem_old · version 41
Customer corrects it
UPDATE mem_old
Friday becomes current
mem_new · version 42
Old fact leaves recall
superseded_by mem_new
CI checks both IDs
require new · forbid old
Four closed operations
Say what happened instead of asking retrieval to infer it.
A correction to current memory
Target an opaque memory ID or stable slot. ContextDB creates the successor and records which prior memory it superseded.
old id → new id + previous idsAn explicit retraction
Remove one target or the current value in a slot. The response lists deleted IDs so the host and its tests can verify the effect.
target or slot → hard deletionA duplicate or no durable change
Record a bounded reason without writing another memory or advancing the memory version.
duplicate → audit event · same versionPython
Correct the fact, then require the next recall to see it.
Every Evolution call requires a stable idempotency key. The result includes the current memory, prior IDs, project-scoped memory version, and primary PostgreSQL WAL position.
Pass both consistency values into a follow-up recall when the next turn must observe the correction.
Install
contextdb-cloud-client==0.2.0a2.
from contextdb_cloud_client import CloudClient
async with CloudClient(
"https://api.contextdb.ai",
api_key="cdb_…",
) as db:
changed = await db.evolve(
"caller-123",
"update",
target_memory_id=current_memory_id,
content="Friday morning works best.",
source="user_stated",
idempotency_key="call-884-correction-v1",
)
current = await db.recall(
"caller-123",
"When should I book the visit?",
min_memory_version=changed.memory_version,
min_primary_wal_lsn=changed.primary_wal_lsn,
)
TypeScript
Retract a fact or record a duplicate without another write.
Target IDs are opaque. Store and pass them unchanged. Cross-project, cross-user, and missing targets all return the same not-found shape.
The package is server-only. Keep the project API key in Node.js, workers, server actions, or another trusted backend.
Install
@contextdb/cloud@0.2.0-alpha.2.
const removed = await db.evolve(
"caller-123",
"delete",
{
targetMemoryId: obsoleteMemoryId,
idempotencyKey: "call-885-retraction-v1",
},
);
const unchanged = await db.evolve(
"caller-123",
"noop",
{
targetMemoryId: currentMemoryId,
noopReason: "duplicate",
idempotencyKey: "call-886-duplicate-v1",
},
);
One atomic mutation
The fact, revision, and write audit commit together.
Project-scoped version
A real state change advances that project's memory version. Another project's writes do not move your consistency floor.
project + mutation → memory_versionPrimary WAL position
The response includes the primary WAL position. A token-bearing recall stays primary-bound unless the caller explicitly chooses bounded replica wait with primary fallback.
write → primary_wal_lsn → recall floorFail-closed target scope
UPDATE and DELETE do not turn a missing or foreign target into an ADD. A target that cannot be proven inside the project and user partition is not found.
unknown target → 404 · no mutationLineage without old content
See the change graph without reopening deleted text.
The Console lineage view returns opaque IDs, lifecycle state, slot, timestamps, supersession links, operation, and reason code. It does not return historical memory content.
After DELETE, the target row is gone. The append-only audit can retain the operation and opaque ID so an operator can verify that a deletion happened without restoring the deleted fact.
{
"nodes": [
{
"memory_id": "mem_old",
"lifecycle_state": "superseded",
"superseded_by": "mem_new"
},
{
"memory_id": "mem_new",
"lifecycle_state": "active"
}
],
"events": [
{
"operation": "SUPERSEDE",
"memory_id": "mem_old",
"related_memory_id": "mem_new"
}
]
}
Formation can plan the same lifecycle
Completed conversations can produce a correction, retraction, or no change.
ContextDB Formation receives bounded, project-scoped current memory alongside PII-processed turns. The hosted planner proposes one of the four operations. Deterministic gates then verify quotes, targets, slots, explicit retractions, and NOOP reasons before commit.
"Actually, make that Friday"
Propose UPDATE against the current appointment-day memory.
correction + known target → UPDATE"Yes, Friday is still right"
Propose NOOP rather than writing a second copy.
same fact + same slot → NOOP"Forget my shipping address"
Propose DELETE only when the turn contains an explicit retraction.
retraction + known target → DELETETest the change, not just the text
Require the new memory ID and forbid the old one.
Memory CI supports deterministic evidence-ID
assertions. A correction test can require mem_new and
forbid mem_old. A deletion test can forbid the deleted ID.
JSON and JUnit exports contain opaque IDs, statuses, counts, outcomes, and machine codes. They omit queries, assertions, and memory content.
case: corrected appointment day
query: "When should I book?"
expected_evidence_ids:
- mem_new
forbidden_evidence_ids:
- mem_old
result: passed
Where it matters
Use Evolution wherever stale memory can change the next action.
Voice scheduling
Correct a caller's appointment day after an explicit statement, then require that version before booking.
Support account changes
Retract obsolete plan or service context so a later agent does not rely on it.
Customer profile sync
Map a changed source record to UPDATE and repeated source versions to NOOP.
Agent-platform memory
Offer one lifecycle contract across frameworks instead of rebuilding correction logic in every agent.
Verified on August 24, 2026
What the bounded hosted proof established.
- Direct ADD, UPDATE, NOOP, and DELETE passed with idempotent replay, project and user isolation, recall floors, and WAL tokens.
- Gemini 2.5 Flash independently selected and committed UPDATE, NOOP, and DELETE against live project-scoped context.
- Metadata-only lineage showed supersession and later deletion without returning historical memory content.
- Memory CI required the current evidence ID, forbade the old ID, and passed through the durable worker.
- Signed audit, content-free exports, plaintext control-state scans, and teardown checks passed.
- Cleanup left zero synthetic projects, organizations, keys, sessions, jobs, attempts, commits, suites, credentials, or memory rows.
This is functional production evidence. It is not sustained-load, failover, availability, latency, COGS, or SLO evidence. The Cloud API, Console, Formation, and clients remain alpha.
Questions
Memory Evolution, answered directly.
What is memory evolution for AI agents?
Memory evolution is the explicit process of adding, correcting, retracting, or leaving factual memory unchanged as new evidence arrives. ContextDB represents those outcomes as ADD, UPDATE, DELETE, and NOOP.
Why not store the correction as another vector?
Two unrelated vectors leave retrieval and the model to decide which statement is current. UPDATE closes the prior memory, links it to the new memory, and returns a consistency floor for the next recall.
Does UPDATE overwrite the old memory?
No. UPDATE creates a new current memory and marks the previous memory as superseded. Metadata-only lineage connects their opaque IDs. Ordinary recall returns the current memory.
Does DELETE keep the deleted memory content?
The target memory row is hard-deleted. Append-only audit and lineage can retain the operation, opaque ID, timestamp, and reason code without returning the deleted content.
Does NOOP advance the memory version?
No. NOOP records why nothing changed and leaves the project memory version unchanged.
Can Formation choose UPDATE or DELETE automatically?
Yes, in Hosted Alpha. The provider proposes an operation from bounded current context and structured turns. Deterministic gates still require a known target and explicit evidence, especially for deletion.
Do I need ContextDB if I only retrieve documents?
No. A conventional RAG stack can be enough for mostly static documents. ContextDB is for per-user facts that change over time and may influence bookings, refunds, updates, or other actions.
Is Memory Evolution generally available?
It is available in the open SDK and Cloud Alpha, with the bounded functional production proof described above. There is no public availability SLO, sustained-load result, or failover claim.
Stop making your model choose between old and current facts.
Start with one correction, pass its consistency token into recall, then add the old ID to Memory CI's forbidden evidence.