Formation
Submit structured turns after a call, chat, or workflow. ContextDB removes PII before the provider, proposes quote-backed ADD, UPDATE, DELETE, or NOOP candidates, applies blocking gates, and either returns them for review or commits them to the correct user partition.
structured turns → 202 job → propose | commit
Short answer: Formation is asynchronous memory creation. The agent finishes its realtime turn. A durable job decides what deserves to become memory afterward.
propose · commit · submit and poll
Review service status
Off the realtime path
A direct remember call is right when your application already
knows the exact fact. Formation is for raw interaction turns that still
need extraction, provenance, confidence, evidence, and a decision about
whether memory should be added, corrected, retracted, or left unchanged.
A required stable idempotency key binds the structured text turns, mode, project, and user partition.
POST /v1/formation/jobs → 202 queued
One dedicated same-VM process claims due work and records an inspectable attempt.
queued | retry_wait → running
Cloud reads at most 50 current factual memories from the exact partition, then PII-processes turns and context before provider execution.
scope → PII gate → bounded context
The provider proposes ADD, UPDATE, DELETE, or NOOP. Every mutating candidate must survive the extractive quote and operation gates below.
provider → validate → accepted | rejected
Propose keeps candidate state encrypted at rest and returns candidate details for review without changing memory. Commit applies the frozen accepted stage under a stable commit identity.
review candidates | write memory
The host polls the job ID until succeeded or failed and can inspect the terminal reason without resending turns.
GET /v1/formation/jobs/{job_id}
The API object
Every submission requires an idempotency key. Repeating the same request resolves to the same job. Changing the payload under that key fails closed.
The poll response shows provider attempts, elapsed time, accepted and rejected counts, operation counts, terminal reason, candidate evidence, lineage IDs, and consistency tokens when commit mode succeeds.
# enqueue POST /v1/formation/jobs Idempotency-Key: call-456-formation-v1 { "user_id": "customer-123", "mode": "propose", "turns": [ {"speaker": "user", "content": "I prefer Saturday mornings."} ] } → 202 {"job_id":"frm_…","status":"queued"} # poll GET /v1/formation/jobs/frm_… → succeeded · completed · candidate accepted
Two modes
turns → encrypted candidate review
Inspect operation, target, candidate content, source, confidence, evidence quote, turn indexes, action relevance, NOOP reason, and rejection reason without changing memory.
validated stage → idempotent memory write
Accepted candidates enter the scoped memory state machine with stable commit identity. The result carries operation counts, current and prior memory IDs, deleted IDs, and a read-your-writes consistency token.
Operation-aware Formation
The provider sees bounded current factual memory from the same project and user partition. It can propose ADD for a new fact, UPDATE for a correction, DELETE for an explicit retraction, or NOOP for a duplicate. ContextDB derives candidate identity and applies deterministic gates before any commit.
| Candidate | Required evidence | Accepted result | Fail-closed result |
|---|---|---|---|
ADD |
Self-contained content, source fields, cited turn indexes, and an exact PII-processed quote from a valid turn. | A server-derived candidate key identifies one new memory. | A missing or non-extractive quote rejects the candidate. |
UPDATE |
An exact supporting quote plus a current target ID or stable entity and attribute slot in the same partition. | The successor records current and prior memory IDs. | A missing or foreign target never becomes a blind ADD. |
DELETE |
A current target or slot and an exact user-stated quote with explicit forget, remove, or retract language. | The result lists deleted IDs. | No retraction quote means no DELETE. |
NOOP |
A bounded snake_case reason and a verified scoped reference. | The audit records why nothing changed. | No memory row is written and the memory version stays unchanged. |
Read the full Memory Evolution guide.
See the result in Console: open Memories.
Durability and safety
One dedicated single-instance Formation process executes beside the gateway on the same app VM. The process is separate. The PostgreSQL job, lease, attempt, encrypted stage/result, and commit state stay durable.
project + job + payload kind
Request, staged candidate, and result payloads use project and job-bound authenticated encryption. Raw turns and candidates do not enter plaintext control columns.
worker_lost → retry_wait | failed
Jobs carry leases, deadlines, provider-attempt limits, and worker limits. Expired leases produce named worker-loss attempts instead of a permanent running state.
frozen stage + stable commit identity
A staged candidate has one commit identity. If a worker exits after the memory write, the next lease owner recovers that memory instead of writing another copy.
Use cases
Extract stable caller preferences after the phone conversation without adding turn latency.
completed call → structured turns
Propose durable account context for operator review before it reaches future agents.
conversation → propose → review
Turn structured human and agent events into sourced memories with a named failure state.
events → durable job → terminal state
Offer post-session memory creation while keeping the platform's realtime runtime independent.
session end → formation
Formation can mark a memory as action-relevant, but it does not authorize the action. ContextDB advises. The customer host enforces. The host applies the result at the action boundary.
Verified on August 24, 2026
claim · lease · terminal · recovery
Real PostgreSQL tests cover claim, lease, synthetic terminal, encrypted result, retry budget, and partial commit recovery.
gateway → separate runtime → gateway poll
A bounded split-ownership CI test disables embedded execution, enqueues through the gateway, commits through a separately assembled runtime in the same test process, and polls through the gateway.
2026-08-24
The August 24 bounded production proof passed propose, identical replay, commit, recall, lineage, consistency, Memory CI, and plaintext control-state scans.
UPDATE · NOOP · DELETE
Gemini 2.5 Flash independently selected and committed UPDATE, NOOP, and DELETE against live project-scoped context.
worker_lost → completed
A later same-VM proof killed the dedicated Formation process, observed a new PID, advanced only the synthetic lease expiry, and reached worker_lost → completed without duplicate memory or commit identities.
mutable proof rows → 0
Cleanup returned zero proof projects, keys, jobs, attempts, commits, suites, credentials, or memory rows.
This is functional and same-VM process-restart evidence, not a broad quality benchmark, COGS result, sustained-load test, high-availability, multi-VM failover, customer-data backup/restore, worker-fleet, or availability SLO evidence. It does not establish exactly-once provider calls or natural wall-clock lease timing.
Formation FAQ
Use remember when your host knows the exact fact. Use Formation when structured turns still need extraction and validation.
No. Submission returns a job ID immediately. The host polls after the interaction while a separate single-instance Formation process runs on the same app VM.
No. The Hosted Alpha contract accepts structured text turns only.
No. Cancellation, job listing, retention cleanup, and scheduling are not part of the current contract.
Yes, in Hosted Alpha. Version-2 jobs can propose and commit UPDATE, DELETE, and NOOP as well as ADD. UPDATE and DELETE require a current target or slot, and DELETE also requires an explicit retraction.
The implementation uses idempotent enqueue, staged candidates, stable commit identity, and recovery tests. ContextDB does not claim exactly-once infrastructure or an availability SLO.
Start with propose mode, inspect one candidate, then decide whether commit fits your workflow.