Memory Evolution
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.
ADD · UPDATE · DELETE · NOOP
Short 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.
one scoped operation → one result
Inspect the open SDK
The Cloud API and Console expose the same closed operations with bounded functional evidence from the hosted service. Hosted Memory Evolution is not generally available. No public availability SLO, sustained-load result, or failover claim is made.
POST /v1/evolve
Review service status
Stale facts
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.
The current fact has an opaque ID and project-scoped memory version.
mem_old · version 41
UPDATE targets the current memory ID or its stable entity and attribute slot.
UPDATE mem_old
The new fact, supersession link, version, WAL position, and write audit commit together.
mem_new · version 42
The caller can pass the version and WAL floors when the next turn must observe the change.
superseded_by mem_new
The case requires the successor and forbids the superseded evidence ID.
require new · forbid old
Four closed operations
| Operation | Input | State result | Returned proof |
|---|---|---|---|
ADD |
Content and source, plus an optional entity and attribute for a stable slot. | A new durable fact becomes active. | Current memory ID, memory version, and primary WAL position. |
UPDATE |
An opaque target memory ID or stable slot, plus corrected content and source. | The successor becomes active and the prior memory becomes superseded. | New memory ID, previous memory IDs, memory version, and WAL position. |
DELETE |
One scoped target ID or the current value in a stable slot. | The target row is hard-deleted. | Deleted memory IDs, memory version, and WAL position. |
NOOP |
A verified scoped reference and bounded reason such as duplicate. |
No memory row changes and the project memory version does not advance. | The NOOP reason and content-free audit event. |
Python
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
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
project + mutation → memory_version
A real state change advances that project's memory version. Another project's writes do not move your consistency floor.
write → primary_wal_lsn → recall floor
The response includes the primary WAL position. The current deployment has no read replica, and its read and primary pools both connect to the primary. Replica wait with primary fallback remains a consistency contract for a topology with a replica. It is not evidence of deployed read scaling.
unknown target → 404 · no mutation
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.
Lineage without old content
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
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.
correction + known target → UPDATE
Propose UPDATE against the current appointment-day memory.
same fact + same slot → NOOP
Propose NOOP rather than writing a second copy.
retraction + known target → DELETE
Propose DELETE only when the turn contains an explicit retraction.
Test current and obsolete evidence
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
Memory Evolution use cases
Correct a caller's appointment day after an explicit statement, then require that version before booking.
UPDATE → consistency floor → action gate
Retract obsolete plan or service context so a later agent does not rely on it.
DELETE → forbid old evidence
Map a changed source record to UPDATE and repeated source versions to NOOP.
source version → UPDATE | NOOP
Offer one lifecycle contract across frameworks instead of rebuilding correction logic in every agent.
one lifecycle contract
A current memory can inform an action, but it does not authorize one. ContextDB advises. The customer host enforces. The host applies the Action Gate outcome before booking, refunding, or changing an account.
Verified on August 24, 2026
ADD · UPDATE · NOOP · DELETE
Direct ADD, UPDATE, NOOP, and DELETE passed with idempotent replay, project and user isolation, recall floors, and WAL tokens.
provider choice → deterministic gates
Gemini 2.5 Flash independently selected and committed UPDATE, NOOP, and DELETE against live project-scoped context.
opaque IDs · no historical content
Metadata-only lineage showed supersession and later deletion without returning historical memory content.
require current · forbid old
Memory CI required the current evidence ID, forbade the old ID, and passed through the durable worker.
audit · exports · scans
Signed audit, content-free exports, plaintext control-state scans, and teardown checks passed.
mutable proof rows → 0
Cleanup left zero synthetic projects, organizations, keys, sessions, jobs, attempts, commits, suites, credentials, or memory rows.
This is bounded functional evidence from the hosted service. It is not sustained-load, failover, availability, latency, COGS, or SLO evidence. Formation remains Hosted Alpha, while the SDK is Available.
Memory Evolution FAQ
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.
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.
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.
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.
No. NOOP records why nothing changed and leaves the project memory version unchanged.
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.
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.
The SDK is Available. Hosted Memory Evolution is on Cloud, not generally available. The evidence above is bounded functional evidence from the hosted service. It does not establish a public availability SLO, sustained-load result, or failover.
Start with one correction, pass its consistency token into recall, then add the old ID to Memory CI's forbidden evidence.