@contextdb/cloud

ContextDB Cloud TypeScript SDK for AI agent memory

Give Node.js voice, support, and workflow agents persistent memory through the hosted ContextDB data plane.

npm install @contextdb/cloud@0.2.0-alpha.2

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

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

const corrected = await db.evolve("caller-1", "update", {
  idempotencyKey: "call-456-correction-v1",
  targetMemoryId: currentMemoryId,
  content: "My preferred visit day is Sunday.",
  source: "user_stated",
});
const retracted = await db.evolve("caller-1", "delete", {
  idempotencyKey: "call-456-retraction-v1",
  targetMemoryId: obsoleteMemoryId,
});
const duplicate = await db.evolve("caller-1", "noop", {
  idempotencyKey: "call-456-duplicate-v1",
  noopReason: "duplicate",
});

Each result exposes requested/applied operation, outcome, optional memory, previous and deleted memory IDs, NOOP reason, memory version, primary WAL position, and request ID. Memory IDs are opaque; pass them unchanged.

Project API keys are server credentials. Do not expose them to browser code. The package is marked server-only and throws if constructed in a browser runtime. Use it from Node.js servers, API routes, workers, or server actions.

Use cases

• Remember caller preferences across Retell, LiveKit, Pipecat, or custom voice agent sessions.
• Ground support responses in previous conversations.
• Require an act/ask/abstain decision before consequential tools run.
• Pass consistency tokens when a follow-up recall must observe a recent write.
• Report execution receipts for an auditable memory-to-action timeline.
• Correct a known memory or stable slot with UPDATE while retaining lineage.
• Retract a target or slot with DELETE and inspect the returned deleted IDs.
• Represent a duplicate as NOOP instead of storing another copy.

Asynchronous Formation

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

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

Jobs accept structured text turns and return closed, inspectable statuses. Formation remains Hosted Alpha with no audio or cancellation contract. Synchronous and asynchronous Formation responses expose operation, opaque target, server-derived candidate key, per-operation results/counts, deleted IDs, and consistency tokens. Legacy candidates without an operation are implicit ADD; the client never manufactures missing operation results.

TypeScript starter kits

• Vercel AI SDK
• PyAI Omni voice agents

Both starters install this package from npm and compile against their current framework dependencies in CI.

Links

• ContextDB API documentation
• Memory Evolution in ContextDB SDK 0.4.1
• ContextDB SDK 0.4.1 package
• Source and OpenAPI contract
• Python SDK
• Open-source ContextDB engine
• Release notes

Status and limitations

This is a server-only Hosted Alpha transport. Formation accepts structured text turns only; there is no audio upload, cancellation, job listing, retention API, or public availability SLO. On August 24, 2026, a bounded hosted proof passed direct ADD, UPDATE, NOOP, and DELETE; real-provider Formation UPDATE, NOOP, and DELETE; consistency, lineage, Memory CI, privacy, and zero-residue cleanup. That proves the functional path, not sustained load, failover, availability, or an SLO. The package contains no hosted planner, worker, tenancy, commit ledger, or recovery code.

FAQ

Which evolution operation should I use?

Use ADD for a new durable fact, UPDATE for a correction, DELETE for an explicit retraction, and NOOP for a duplicate or no durable change. UPDATE and DELETE need an opaque target ID or an entity/attribute slot.

Can I call evolve from a browser?

No. A cdb_ key is a project-wide server credential. The constructor fails closed when window exists.

Is this package production-ready?

The package is alpha and contains no ContextDB Cloud server implementation. The bounded hosted proof establishes the functional path only. It does not establish sustained-load behavior, failover, availability, or a public SLA.