Skip to content

Async memory formation API for AI agents

Pre-release
Pre-release

Choose a tag to compare

View all tags
@atomsai atomsai released this 21 Aug 09:55
v0.1.0-alpha.6
e4bf8b3
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Async memory formation API for AI agents

ContextDB Cloud clients now support durable asynchronous Formation jobs.
Applications can submit structured conversation turns after a call, chat, or
workflow, receive a job ID immediately, and poll a closed, inspectable status.

The realtime agent path stays unblocked. ContextDB operates extraction,
validation, optional commit, retries, and failure recovery behind the public
contract.

Python

Install:

pip install --pre contextdb-cloud-client==0.1.0a5

Submit and poll:

submitted = await db.submit_formation_job(
    "caller-1",
    [{"speaker": "user", "content": "I prefer Saturday mornings."}],
    mode="propose",
    max_memories=5,
    deadline_seconds=25,
    idempotency_key="call-456-formation-v1",
)

job = await db.get_formation_job(submitted.job_id)

TypeScript

Install:

npm install @contextdb/cloud@0.1.0-alpha.6

Submit and poll:

const submitted = await db.submitFormationJob(
  "caller-1",
  [{ speaker: "user", content: "I prefer Saturday mornings." }],
  {
    mode: "propose",
    maxMemories: 5,
    deadlineSeconds: 25,
    idempotencyKey: "call-456-formation-v1",
  },
);

const job = await db.getFormationJob(submitted.job_id);

Public contract

  • POST /v1/formation/jobs
  • GET /v1/formation/jobs/{job_id}
  • Required Idempotency-Key for every submission
  • Modes: propose and commit
  • Closed job, terminal-reason, and attempt statuses
  • Candidate source, confidence, action relevance, evidence quote, and rejection
    reason
  • Commit memory IDs plus memory-version and WAL consistency token
  • Named provider, deadline, worker-loss, validation, storage, and configuration
    failures

Security and open-core boundary

The repository contains request/response contracts and thin clients only. It
does not contain the hosted worker, leases, credentials, encryption keys,
tenant control plane, retry coordinator, commit recovery, metering, or
operations.

Provider tokens, transcripts, candidate payloads, and customer memory remain
server-side. Polling one job requires the same project key that created it.

Verification

  • Python client suite passes Formation submission, idempotency, status parsing,
    attempts, and candidate parsing.
  • TypeScript client suite passes submit and content-free poll contracts.
  • OpenAPI 3.1 validation passes.
  • Public boundary enforcement passes.
  • Hosted real-PostgreSQL Formation recovery tests passed separately in the
    private Cloud repository.

Status and limitations

Formation is Hosted Alpha. It accepts structured text turns only. There is no
audio upload, cancellation API, job listing, retention API, multi-region
availability claim, or public SLO. Cost can remain unknown when a provider does
not expose a fixed call cost.

Links

Assets 5
Loading