Async memory formation API for AI agents

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

• ContextDB API documentation
• OpenAPI contract
• Python package
• TypeScript package
• Agent framework starter kits

AI agent memory starter kits: OpenAI, LangGraph, Vercel, LiveKit, and PyAI

ContextDB memory starter kits for OpenAI Agents, LangGraph, Vercel AI SDK, LiveKit, and PyAI

ContextDB now ships five public starter applications for adding persistent,
action-aware memory to popular agent frameworks.

Framework session state solves the current thread. These starters show the
separate lifecycle needed for selected user facts that must survive a new
thread, process, deployment, room, or phone call.

Included starter kits

• OpenAI Agents SDK for Python
• LangGraph for Python
• Vercel AI SDK for TypeScript
• LiveKit Agents with PyAI speech
• PyAI Omni with the official Twilio bridge

Each starter demonstrates:

• stable server-side user partitioning,
• recall before the model answers,
• guarded ContextDB context injection,
• deliberate memory writes instead of transcript dumping,
• action evaluation before external side effects,
• server-only credential handling,
• a direct path to the hosted Memory Testbench.

One-command start

npx degit atomsai/contextdb-clients/starters contextdb-agent-starters
cd contextdb-agent-starters/openai-agents-python

Choose another starter directory to use a different framework.

Client releases

• Python: contextdb-cloud-client==0.1.0a4
• TypeScript: @contextdb/cloud@0.1.0-alpha.5

The client APIs are unchanged. These releases update package discovery,
examples, and version metadata. The Python package's exported __version__
now matches its package metadata.

Verification

• Python examples install and import against pinned current framework versions.
• TypeScript examples install from lockfiles and pass strict TypeScript checks.
• Public boundary CI rejects hosted control-plane symbols in clients and
  starter source.
• The existing Python and TypeScript client suites remain unchanged and green.

Links

• ContextDB Cloud
• Memory Testbench
• Python package
• TypeScript package
• Open-source ContextDB engine

Status and limitations

The starters, clients, and hosted service are alpha. They are reference
applications, not deployment templates or availability guarantees. External
framework APIs were verified on 2026-08-21. Review identity mapping, retention,
error handling, provider terms, and action policy for your application.

ContextDB Cloud TypeScript SDK 0.1.0-alpha.4: Server-Only AI Agent Memory

Use persistent AI agent memory without exposing project keys in browser code

@contextdb/cloud 0.1.0-alpha.4 is the server-only TypeScript SDK for ContextDB Cloud. It gives Node.js voice, support, and workflow agents typed access to memory writes, recall, consistency tokens, action decisions, confirmations, execution receipts, and verifiable deletion.

This release fails closed in browser runtimes and tells bundlers the package is not browser-compatible. ContextDB project keys remain backend credentials.

Install

npm install @contextdb/cloud

Example: remember a caller preference from a Node.js service

import { CloudClient } from "@contextdb/cloud";

const db = new CloudClient({
  baseUrl: "https://api.contextdb.ai",
  apiKey: process.env.CONTEXTDB_API_KEY!,
});

const saved = await db.remember(
  "caller-1",
  "Tuesday morning works best",
  {
    source: "user_stated",
    idempotencyKey: "call-42-preference",
  },
);

const recalled = await db.recall(
  "caller-1",
  "When should I schedule the appointment?",
  {
    minMemoryVersion: saved.memory_version,
    minPrimaryWalLsn: saved.primary_wal_lsn,
  },
);

Use cases

• Retell, LiveKit, and Pipecat voice agents: remember caller preferences across sessions.
• Customer support agents: ground responses in prior conversations and confirmed constraints.
• Workflow agents: require act/ask/abstain decisions before consequential tools run.
• Read-after-write turns: use consistency tokens when the next recall must see a recent memory change.
• Privacy workflows: delete scoped memories and verify removal.

Security changes

• CloudClient throws when constructed in a browser runtime.
• package.json declares browser: false for bundlers.
• Published JavaScript and declaration source maps were removed.
• The package contains no API keys, connection strings, environment values, private Cloud server code, or absolute build paths.
• Full client source remains public for auditability.

Package proof

• 17 tests passed, including browser rejection.
• The npm tarball contains 10 files and zero source maps.
• The package is public and was published through GitHub OIDC provenance.

Links

• Install @contextdb/cloud on npm
• ContextDB Cloud documentation
• Public source and OpenAPI contract
• Python SDK on PyPI
• Open-source ContextDB engine

Can I use this SDK in a Next.js app?

Yes, but only in server routes, server actions, workers, or other backend-only modules. Never import it into a client component or expose a cdb_ key to browser JavaScript.

Is it production-ready?

No. The SDK and hosted service are alpha, and no public availability SLA is claimed.

Start with the ContextDB Cloud documentation.

ContextDB Cloud SDKs 0.1.0-alpha.2: Python and TypeScript AI Agent Memory Clients

Add persistent, action-aware memory to Python and TypeScript AI agents

ContextDB Cloud SDKs 0.1.0-alpha.2 give backend developers typed clients for remembering user context, recalling it with read-your-writes consistency, evaluating consequential actions, recording confirmations, reporting execution outcomes, and verifying deletion.

The packages are thin transports over the hosted API. They do not contain the private multi-tenant server, managed-source runtime, billing system, or enterprise control plane.

Install

Python:

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

TypeScript:

npm install @contextdb/cloud@alpha

Python example: remember and immediately recall a caller preference

from contextdb_cloud_client import CloudClient

async with CloudClient(
    "https://api.contextdb.ai",
    api_key="cdb_...",
) as db:
    saved = await db.remember(
        "caller-1",
        "Tuesday morning works best",
        source="user_stated",
        idempotency_key="call-42-preference",
    )
    result = await db.recall(
        "caller-1",
        "When should I schedule the appointment?",
        min_memory_version=saved.memory_version,
        min_primary_wal_lsn=saved.primary_wal_lsn,
    )

TypeScript example: gate a consequential action

import { CloudClient } from "@contextdb/cloud";

const db = new CloudClient({
  baseUrl: "https://api.contextdb.ai",
  apiKey: process.env.CONTEXTDB_API_KEY!,
});

const decision = await db.evaluateAction(
  "caller-1",
  "Book the Tuesday appointment",
);

if (decision.outcome === "act") {
  // Execute in your host, then report the outcome.
}

Use cases

• AI voice agents: remember language, appointment, accessibility, and confirmed caller preferences across calls.
• Customer support agents: ground replies in prior context without treating a wish as an approved action.
• Workflow agents: link evidence, act/ask/abstain decisions, confirmations, and execution receipts.
• Privacy operations: delete one memory or a complete user partition and verify removal.

What changed in alpha.2?

• Search-oriented package pages with runnable examples and named use cases.
• Clear links between Python, TypeScript, the OpenAPI contract, hosted docs, and the open-source engine.
• Direct FAQ answers and explicit alpha limitations for developers and answer engines.
• Normalized npm package metadata and public Apache-2.0 licensing.

Links

• ContextDB Cloud documentation
• Python package on PyPI
• TypeScript package on npm
• Public client source and OpenAPI contract
• Open-source ContextDB engine

Is this production-ready?

No. The clients and hosted service are alpha, and no public availability SLA is claimed. Project keys are backend credentials and must never be embedded in browser code.

Start with the ContextDB Cloud documentation, then install the client for your backend language.

ContextDB Cloud clients 0.1.0-alpha.1

First public alpha of the thin ContextDB Cloud clients and strict API contract.

Artifacts:

• contextdb-cloud-client Python wheel and source distribution
• @contextdb/cloud npm-compatible tarball
• Source and OpenAPI contract in this repository

The hosted server implementation is not included.

Registry publication is pending PyPI trusted-publisher and npm organization authentication.