Machine-ready integration guide

Integrate ContextDB with an AI coding agent.

Give your coding agent the credential boundary, official SDKs, OpenAPI contracts, canonical action flow, and current Cloud Alpha limits before it edits your server application.

recall → remember → evaluate_action → confirm if required → re-evaluate → host action → report_execution

Read the plain-text agent guide Read the repository agent rules Browse the complete site directory

Credential boundary

Call ContextDB only from trusted server code.

Keep project keys in server secret storage and Memory CI tokens in CI secret storage. Never place either credential in browser JavaScript, a mobile binary, a log, a prompt, a fixture, or a generated file. user_id selects one project-scoped memory partition. It is not end-user authentication.

CONTEXTDB: Stores sourced memory and returns an advisory act, ask, or abstain outcome.
CUSTOMER HOST: Authenticates the end user, authorizes the request, checks current state, and runs the action.
CREDENTIALS: Use CONTEXTDB_API_KEY on the server and CONTEXTDB_EVAL_TOKEN in CI.

Official clients and contracts

Choose an SDK, then verify behavior against OpenAPI.

The Cloud clients are thin server-side clients for the hosted API. Use the Apache-2.0 SDK when you need the local or self-hosted engine.

Resource	Use	Link
Python Cloud client	Python servers, workers, and agent runtimes	Open the Python package
TypeScript Cloud client	Node.js servers, API routes, workers, and server actions	Open the TypeScript package
Apache-2.0 SDK	Local and self-hosted memory semantics	Open the public SDK
Memory API OpenAPI 3.1	Hosted memory, Formation, action, receipt, and erasure contracts	Open the Memory API contract
Memory CI OpenAPI 3.1	Hosted suite run, status, cancellation, and export contracts	Open the Memory CI contract

Canonical client flow

Keep the consequential action below the policy branch.

Client evaluate_action maps to HTTP and MCP recall_for_action. ContextDB records the decision. It does not execute or block the downstream action.

Resolve identity in the host. Derive a stable customer partition from authenticated server context.
Recall and write selected memory. Recall at session start. Store only durable facts with their real source and stable idempotency keys.
Evaluate before a consequential tool. Call evaluate_action before a booking, refund, account change, or other business write.
Branch on act, ask, or abstain. On ask, authenticate the end user, retain any attestation, confirm one returned memory ID, and evaluate again. On abstain, do not act.
Enforce and report in the host. On act, apply authorization and current-state checks, run the action, then report succeeded, failed, or skipped with the decision ID.

Current maturity

Preserve the status labels in code and documentation.

The Apache-2.0 SDK is available for local and self-hosted use. The hosted memory API and console are Cloud Alpha. Asynchronous Formation, hosted Memory CI, and the stateless tools-only MCP endpoint are Hosted Alpha. Managed Sources is feature-gated Private Alpha. Production operation is not claimed. There is no availability SLA or high-availability topology.

Review current component status Review current security controls Review the SDK and Cloud boundary

Copyable implementation prompt

Give your coding agent the same integration boundary.

Integrate ContextDB into this repository.

Read https://contextdb.ai/for-agents.txt and
https://contextdb.ai/openapi.yaml before editing.

Inspect the repository and identify server-only integration points. Use
CONTEXTDB_API_KEY only through server secret storage. Never expose it to browser
or mobile code. Derive user_id from authenticated host context.

Implement the canonical flow:
recall -> remember -> evaluate_action -> confirm if required -> re-evaluate ->
host action -> report_execution.

Keep authentication, authorization, current-state checks, and the final action
in the customer host. Stop on ask or abstain. Use stable idempotency keys for
writes and receipts. Add tests for cross-user isolation, each action outcome,
retries, and credential exposure.

Show the proposed integration points before editing.

Verify the integration against the API reference.

Use the machine guide for context and OpenAPI for request and response shapes.

Open the API reference Open the plain-text guide