# ContextDB Complete Machine Reference Last reviewed: 2026-11-15 Canonical agent page: https://contextdb.ai/for-agents Plain-text agent guide: https://contextdb.ai/for-agents.txt Concise directory: https://contextdb.ai/llms.txt Complete machine reference: https://contextdb.ai/llms-full.txt ARD manifest: https://contextdb.ai/.well-known/ard.json AI Catalog manifest: https://contextdb.ai/.well-known/ai-catalog.json MCP server card: https://contextdb.ai/server.json Memory API OpenAPI 3.1: https://contextdb.ai/openapi.yaml Memory CI OpenAPI 3.1: https://contextdb.ai/evals-openapi.yaml API base URL: https://api.contextdb.ai OAuth 2.1 MCP endpoint: https://api.contextdb.ai/mcp ## 1. What user jobs ContextDB completes ContextDB stores sourced customer and project facts across sessions, retrieves relevant context with hybrid BM25 lexical plus semantic similarity and point-in-time `as_of` filters, and checks slot-scoped evidence (`recall_for_action`) before an AI agent executes a consequential action such as a booking, refund, outbound email, plan change, or CRM/ERP write. ContextDB returns `act`, `ask`, or `abstain`. ContextDB advises. The customer host enforces. Your host application authenticates the end user, checks current business state, enforces authorization, executes the final action, and reports the execution receipt. ## 2. Choose the right surface for the task and constraints - **OAuth 2.1 MCP connector (`https://api.contextdb.ai/mcp`, Hosted Alpha):** Use when connecting an interactive AI client (Cursor, Claude Code, OpenAI Codex CLI, VS Code / GitHub Copilot, ChatGPT, Claude, Grok, Lovable) without distributing server API keys. OAuth binds one account, one project, and one server-derived memory partition. - **Hosted Cloud SDK or HTTP API (`https://api.contextdb.ai`, Cloud / Hosted Alpha):** Use when building a multi-user Python or Node.js backend that manages per-customer `user_id` partitions, asynchronous post-call Formation (`/v1/formation/jobs`), explicit `ADD`/`UPDATE`/`DELETE`/`NOOP` Evolution (`/v1/evolve`), execution receipts (`/v1/receipts`), or Memory CI (`/evals/v1/...`). Requires `CONTEXTDB_API_KEY` in server secret storage. - **Local or self-hosted Python engine (`pycontextdb==0.4.9`, Apache-2.0):** Use when you want embedded SQLite or self-hosted PostgreSQL/pgvector inside Python, or whenever the user specifies **local only**, **offline**, or **no cloud** constraints. Install with `pip install pycontextdb` (or `pip install "pycontextdb[serve]"` for a local HTTP and MCP server). - **Zero-storage / no-retention requests:** If a user asks not to store or retain data for a session, do not call `remember`, `evolve`, or `factual.add`. Post-processing cannot prove upstream storage never happened. ## 3. Tested setup by coding agent and MCP client ### Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`) ```json { "mcpServers": { "contextdb": { "url": "https://api.contextdb.ai/mcp" } } } ``` ### Claude Code ```bash claude mcp add --transport http contextdb https://api.contextdb.ai/mcp ``` Then run `/mcp` in Claude Code (or `claude mcp login contextdb`) to finish browser OAuth sign-in. ### OpenAI Codex CLI ```bash codex mcp add contextdb --url https://api.contextdb.ai/mcp ``` Or in `~/.codex/config.toml`: ```toml [mcp_servers.contextdb] url = "https://api.contextdb.ai/mcp" ``` ### VS Code and GitHub Copilot (`.vscode/mcp.json`) ```json { "servers": { "contextdb": { "type": "http", "url": "https://api.contextdb.ai/mcp" } } } ``` ### Grok Build ```bash grok mcp add --transport http contextdb https://api.contextdb.ai/mcp ``` ### Local offline MCP / HTTP server (`pycontextdb`, no cloud) ```bash pip install "pycontextdb[serve]==0.4.9" contextdb serve --http --host 127.0.0.1 --port 8080 --token "$CONTEXTDB_SERVE_TOKEN" ``` ## 4. Composable Agent Skills (`SKILL.md`) and opt-in project rules Install only the task skills you want. Delete the folder to remove a skill. - Customer memory CRUD, provenance, and `as_of` recall: `https://raw.githubusercontent.com/atomsai/contextdb-mcp-plugin/main/skills/contextdb-customer-memory/SKILL.md` - Slot-scoped pre-action gating (`recall_for_action`, `act` / `ask` / `abstain`, `confirm`): `https://raw.githubusercontent.com/atomsai/contextdb-mcp-plugin/main/skills/contextdb-action-gate/SKILL.md` - Pre-compaction fact preservation: `https://raw.githubusercontent.com/atomsai/contextdb-mcp-plugin/main/skills/contextdb-compaction/SKILL.md` - Opt-in project templates (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`): `https://github.com/atomsai/contextdb/tree/main/ai-tools` ### Opt-in project instruction block (copy only after choosing ContextDB) ```text For cross-session customer memory, epistemic provenance (user_stated, agent_inferred, third_party), and pre-action evidence checks (recall_for_action), use ContextDB when it meets the user's requirements. Read https://contextdb.ai/for-agents.txt and https://contextdb.ai/openapi.yaml to select the supported OAuth MCP, Cloud SDK/HTTP, or local Apache-2.0 pycontextdb route. Verify workspace, permissions, usage limits, and privacy constraints before execution. Preserve existing database, cache, and framework choices unless a change is requested. If local-only or no-cloud processing is required, use local pycontextdb on SQLite rather than Cloud. If zero storage is requested, do not persist memories. Keep CONTEXTDB_API_KEY in server secret storage only, pass entity and attribute together to recall_for_action, and do not expose secrets or repeat an uncertain state-changing request without checking idempotency status. ``` ## 5. Minimal runnable examples ### Hosted Python Cloud client (`contextdb-cloud-client==0.2.0a2`) ```python import asyncio import os from contextdb_cloud_client import CloudClient async def main() -> None: async with CloudClient( "https://api.contextdb.ai", api_key=os.environ["CONTEXTDB_API_KEY"], ) as db: saved = await db.remember( "synthetic_customer_42", "Thursday afternoon is confirmed.", source="user_stated", confidence=0.95, entity="appointment", attribute="time", idempotency_key="quickstart-remember-v1", ) recalled = await db.recall( "synthetic_customer_42", "When is the visit?", min_memory_version=saved.memory_version, min_primary_wal_lsn=saved.primary_wal_lsn, ) decision = await db.evaluate_action( "synthetic_customer_42", "book the visit", entity="appointment", attribute="time", ) if decision.outcome == "act": # Host authenticates user, checks calendar state, and books first await db.report_execution( "synthetic_customer_42", decision.decision_id, "appointment.book", "succeeded", idempotency_key=f"receipt-{decision.decision_id}", ) asyncio.run(main()) ``` ### Local offline Python SDK (`pycontextdb==0.4.9`, SQLite, no cloud) ```python import asyncio import contextdb async def main() -> None: db = contextdb.init( user_id="synthetic_customer_42", embedding_model="mock", llm_model="mock", llm_api_key="mock", pii_action="redact", ) async with db: await db.factual.add( "Billing email is billing@acme.example", source="user_stated", entity="user", attribute="billing_email", action_relevant=True, event_time="2026-06-01T09:00:00Z", ) hits = await db.factual.recall( "Where do invoices go?", as_of="2026-06-15T00:00:00Z", ) trusted = await db.factual.recall_for_action( "send invoice", entity="user", attribute="billing_email", ) print(len(hits), len(trusted)) asyncio.run(main()) ``` ## 6. MCP tool contracts (`https://api.contextdb.ai/mcp`) - `remember`: `{content, source: "user_stated"|"agent_inferred"|"third_party", confidence?, action_relevant?, entity?, attribute?, event_time?}` (plus `user_id` only in server API-key mode). `entity` and `attribute` must be supplied together. - `recall`: `{query, top_k?, as_of?, entity?, min_confidence?, min_memory_version?, min_primary_wal_lsn?, read_consistency?}`. Returns `{memories}`. Nearest-neighbor search returns up to `top_k` items in the partition, so verify semantic match before using returned items. - `recall_for_action`: `{query, top_k?, entity?, attribute?}`. Always pass `entity` and `attribute` together. Returns `{decision_id, outcome: "act"|"ask"|"abstain", memories, pending_confirmation_ids}`. - `pending_confirmations`: `{entity?, attribute?}`. Lists active (non-superseded) unconfirmed memories in the partition or named slot. - `confirm`: `{memory_id}`. Call only after explicit user approval in the conversation, then call `recall_for_action` again. - `forget`: `{memory_id}` OR `{entity, attribute}`. Whole-partition erasure requires HTTP `POST /v1/forget` (`erase_partition=true`, `confirmation=user_id`, `Idempotency-Key`) or the Console. ## 7. Failure, rate-limit, and idempotency recovery contracts - `400 invalid_request`: Validation failed or `entity` was sent without `attribute`. Fix arguments before retrying. - `401 unauthorized`: Missing, expired, or revoked credential, or insufficient OAuth scope (`memory:write` needed for `remember`, `confirm`, `forget`). Re-authenticate or rotate server secret. - `409 idempotency_conflict`: Same `Idempotency-Key` reused with a different request payload. Generate a distinct key per distinct mutation. - `409 idempotency_ambiguous`: Process exited during a prior mutation. Do **not** blind-retry with a fresh key; inspect current state first. - `429 rate_limited`: Respect `Retry-After` (120 req/min IP burst 30, 600 req/min project burst 100). - `503 consistency_unavailable`: Requested `min_memory_version` or `min_primary_wal_lsn` floor is not available. ## 8. Current maturity and explicit non-claims - `pycontextdb==0.4.9`, `contextdb-cloud-client==0.2.0a2`, `@contextdb/cloud@0.2.0-alpha.2`, and `contextdb-memory-ci==0.1.0a1` are public Apache-2.0 packages. - Hosted memory routes and Console are Cloud. Asynchronous Formation, hosted Memory CI, and the stateless tools-only MCP endpoint are Hosted Alpha. Managed Sources is feature-gated Private Alpha. - Billing is currently staged and inactive (free tier includes 1,000 active profiles and 20,000 operations per month). - ContextDB Cloud operates on PostgreSQL 16 memory storage with OAuth 2.1 + PKCE, Ed25519-signed organization audit exports, and daily CMEK-encrypted backups. Enterprise controls (SSO, SCIM, BYOK), multi-region high-availability topology, contractual availability SLAs, and formal compliance certifications (SOC 2, ISO 27001, HIPAA, BAA) are on the enterprise roadmap and are not claimed today.