ContextDB Cloud Python SDK for AI agent memory

Remote client for the ContextDB Cloud data plane. The hosted API and this package are alpha and do not carry a production availability commitment.

pip install contextdb-cloud-client==0.2.0a1

Correct, retract, or deduplicate memory

from contextdb_cloud_client import CloudClient

async with CloudClient("https://api.contextdb.ai", api_key="cdb_…") as cdb:
    corrected = await cdb.evolve(
        "caller-1",
        "update",
        idempotency_key="call-456-correction-v1",
        target_memory_id=current_memory_id,
        content="My preferred visit day is Sunday.",
        source="user_stated",
    )
    retracted = await cdb.evolve(
        "caller-1",
        "delete",
        idempotency_key="call-456-retraction-v1",
        target_memory_id=obsolete_memory_id,
    )
    duplicate = await cdb.evolve(
        "caller-1",
        "noop",
        idempotency_key="call-456-duplicate-v1",
        noop_reason="duplicate",
    )

EvolutionResult exposes requested/applied operation, outcome, optional memory, previous and deleted memory IDs, NOOP reason, memory_version, primary_wal_lsn, and request_id. Target IDs are opaque; store and pass them unchanged.

Full memory lifecycle

from contextdb_cloud_client import CloudClient

async with CloudClient("https://api.contextdb.ai", api_key="cdb_…") as cdb:
    saved = await cdb.remember(
        "caller-1", "Thursday works", source="user_stated",
        confidence=0.9, idempotency_key="call-456-preference-v1",
    )
    context = await cdb.recall(
        "caller-1",
        "when can they come in?",
        min_memory_version=saved.memory_version,
        min_primary_wal_lsn=saved.primary_wal_lsn,
    )
    decision = await cdb.evaluate_action("caller-1", "book the visit")
    if decision.outcome == "act":
        # Execute in your host, then close the Action Ledger.
        await cdb.report_execution(
            "caller-1", decision.decision_id, "appointment.book", "succeeded",
            idempotency_key=f"receipt-{decision.decision_id}",
            external_ref="appt-8842",
        )
    pending = await cdb.pending_confirmations("caller-1")

    # Hosted Alpha formation: enqueue, then poll.
    submitted = await cdb.submit_formation_job(
        "caller-1",
        [{"speaker": "user", "content": "I prefer Saturday mornings."}],
        mode="propose",
        idempotency_key="call-456-formation-v1",
    )
    formation = await cdb.get_formation_job(submitted.job_id)

LocalClient wraps the in-process memory calls for offline development. Cloud-only control-plane features such as durable action decisions and execution receipts require CloudClient.

The API key is a project-wide server credential (cdb_…). Keep it in your server's secret store; never in a browser or client-side code.

Pass a stable idempotency_key to every evolve call and when retrying remember, remember_many, confirm, or extract_memories(..., mode="commit"). Reuse the key only for the exact same logical request. submit_formation_job always requires one. It accepts structured text turns only; no audio or cancellation contract exists.

Delete one bad memory with forget(user_id, memory_id=...). Whole-partition erasure is deliberately harder: pass erase_partition=True, confirmation=user_id, and an idempotency_key; Cloud deletes the partition and verifies that no memory rows or vector-index IDs remain.

Use cases

• AI voice agents: remember caller preferences and confirmed constraints across calls.
• Customer support agents: retrieve prior context while requiring trusted evidence before consequential actions.
• Workflow agents: record act/ask/abstain decisions and report execution outcomes.
• Privacy operations: delete one memory, a stable slot, or a complete user partition with verification.
• Corrections: UPDATE a known memory or stable slot while preserving previous IDs as lineage.
• Retractions: DELETE an opaque target or slot and inspect the returned deleted IDs.
• Duplicates: return an explicit NOOP reason instead of storing another copy.

Formation candidates and job reviews expose operation, target, server-derived candidate key, operation results/counts, deleted IDs, and consistency tokens. Legacy candidates with no operation are read as implicit ADD. Missing operation results are never synthesized from memory IDs.

Status and limitations

This is a thin Hosted Alpha transport. Formation accepts structured text turns only; there is no audio upload, cancellation, job listing, retention API, public availability SLO, or published hosted production proof. The package contains no hosted planner, worker, tenancy, commit ledger, or recovery code.

Python starter kits

• OpenAI Agents SDK
• LangGraph
• LiveKit Agents with PyAI speech

Each starter installs this package and is checked against the documented framework imports in CI.

Links

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

FAQ

Which 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.

Is idempotency_key optional for evolution?

No. The client validates the 8–128 character key before transport.

Is this package production-ready?

No. contextdb-cloud-client and the hosted service are alpha. The package does not claim a public availability SLA or hosted production proof.