# ContextDB integration guide for AI coding agents

Last reviewed: 2026-08-27

Canonical page: https://contextdb.ai/for-agents
Machine guide: https://contextdb.ai/for-agents.txt
Repository agent rules: https://contextdb.ai/AGENTS.md
API base URL: https://api.contextdb.ai

## What ContextDB does

ContextDB stores sourced customer memory across sessions and evaluates remembered
evidence before a customer host runs a consequential action. ContextDB returns
act, ask, or abstain. The customer host owns authentication, authorization,
current-state checks, execution, and enforcement.

## Credentials

- Keep `CONTEXTDB_API_KEY` in server-side secret storage.
- Keep `CONTEXTDB_EVAL_TOKEN` in CI secret storage.
- Never expose either credential in browser code, mobile code, logs, prompts,
  fixtures, screenshots, commits, or generated files.
- `user_id` selects a project-scoped memory partition. It is not end-user
  authentication.

## SDKs and contracts

- Python Cloud client: https://pypi.org/project/contextdb-cloud-client/
- TypeScript Cloud client: https://www.npmjs.com/package/@contextdb/cloud
- Apache-2.0 local SDK: https://github.com/atomsai/contextdb
- Cloud client source and starters: https://github.com/atomsai/contextdb-clients
- Memory API OpenAPI 3.1: https://contextdb.ai/openapi.yaml
- Memory CI OpenAPI 3.1: https://contextdb.ai/evals-openapi.yaml
- API reference: https://contextdb.ai/docs
- MCP guide: https://contextdb.ai/mcp

## Canonical client flow

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

1. Derive a stable customer partition from authenticated server context.
2. Recall selected customer memory when the agent session begins.
3. Write selected durable facts with their real source and stable idempotency keys.
4. Call client `evaluate_action` before a booking, refund, account change, or
   other consequential write. HTTP and MCP name this operation
   `recall_for_action`.
5. Branch on `act`, `ask`, or `abstain`.
6. On `ask`, authenticate the end user in the host, retain any attestation,
   confirm one returned memory ID, and evaluate the action again.
7. On `act`, apply host authorization and current-state checks before execution.
   On `abstain`, do not run the action.
8. Report `succeeded`, `failed`, or `skipped` with the decision ID and a stable
   idempotency key.
9. Use scoped deletion or verified whole-partition erasure when required.

## Current maturity

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

## Copyable coding-agent prompt

```text
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.
```