# CortexDB

> CortexDB is the long-term memory layer for AI agents: a temporal, append-only server that captures
> experiences and serves stratified recall (Events, Episodes, Facts, Beliefs, Understanding) over one v1
> HTTP API. Self-hosting is the recommended way to run it (`docker run cortexdb/cortexdb`), and a managed
> cloud is also available.

## By task — go straight to the one page that answers it

Each route names the page to read and why that page rather than its neighbours. Read only the linked page.

- Run a server on my machine → [Self-Hosting Quickstart](https://cortexdb.ai/docs/self-hosting/quickstart). One `docker run`, then a first write and recall. The Self-Hosting overview is orientation; Defaults is what is off by default.
- Upgrade a running server, clients or connectors → [Upgrading](https://cortexdb.ai/docs/self-hosting/upgrading). What each release changes for existing data, and how to roll back.
- Store a memory / write to CortexDB → [POST /v1/experience](https://cortexdb.ai/docs/api-reference/experience). Required fields, `?wait=` modes, idempotency keys, bulk. The Experience Envelope concept page explains the shape but not the request.
- Get context for a prompt → [POST /v1/recall](https://cortexdb.ai/docs/api-reference/recall). Views, `include`, budgets, `context_block`. Hybrid Retrieval explains why results rank as they do; Recall Tuning is the env knobs.
- Ask a question and get a cited answer → [POST /v1/answer](https://cortexdb.ai/docs/api-reference/answer). Self-hosted, the answer lane is opt-in: configure it per [LLM & Answer](https://cortexdb.ai/docs/operations/llm-answer) first.
- Delete one person's data (GDPR) → [Erasures](https://cortexdb.ai/docs/api-reference/erasures). Preview (with the same selector you will execute), execute, poll; the selector-driven path that removes WAL rows (retention sweeps also remove them by age). `/v1/forget` is selective (derived layers or redaction), not erasure.
- Remove something I stored by mistake → [POST /v1/forget](https://cortexdb.ai/docs/api-reference/forget). Preview then execute with `from_preview_id`; leaves an audit record.
- Understand how a request is authenticated → [Authorization](https://cortexdb.ai/docs/concepts/authorization). `CORTEX_API_KEY` as bearer, `CORTEX_INSECURE_NO_AUTH=1` for loopback dev, tokens and capabilities. Minting tokens for users is [Auth](https://cortexdb.ai/docs/api-reference/auth).
- Name scopes for a tenant or app → [Scopes](https://cortexdb.ai/docs/concepts/scopes). `type:id` segments, allowed types, hierarchy. Registering and listing them is [/v1/scopes](https://cortexdb.ai/docs/api-reference/scopes).
- Facts / Beliefs / Understanding are empty → [Defaults & prerequisites](https://cortexdb.ai/docs/self-hosting/defaults). Enrichment is opt-in on self-host; events and vector recall work without it. If enrichment is on and layers lag, poll [Derivation status](https://cortexdb.ai/docs/api-reference/derivation-status).
- Change the embedding model on an existing store → [Embeddings](https://cortexdb.ai/docs/operations/embeddings). The pin, why a dimension change is refused, and the offline `CORTEX_EMBEDDING_REBUILD_VECTORS` migration.
- Give Claude Code / Cursor / VS Code memory → [MCP Server](https://cortexdb.ai/docs/sdks/mcp-server). Install, per-client config, env vars, the tool list. The Coding Agents page is the chooser between MCP and a rules file.
- Sync Slack, Jira, GitHub, Notion into memory → [Connectors](https://cortexdb.ai/docs/connectors). `cortexdb-sync`, `--scope-template`, credentials model, then the per-source page for its env vars.
- Expire old data / reclaim WAL space → [Retention & WAL](https://cortexdb.ai/docs/operations/retention-wal). Per-scope rules, dry-run sweeps, compaction.
- Ingest PDFs, images, audio → [Media Ingestion](https://cortexdb.ai/docs/features/media-ingestion). Upload a blob, then reference it with its text in `content.transcript` (text blobs need none).
- Index a code repository → [Code Plane](https://cortexdb.ai/docs/features/code-plane). `CORTEX_CODE_PLANE=1`, mount the repo, `/v1/code/*`.
- Store or recall non-English memories (Hindi, Hinglish, other scripts) → [Languages & Multilingual Memory](https://cortexdb.ai/docs/features/languages). Nothing is translated; tag captures, gate on `capabilities[]`, send a `query_variants` entry in the memories' script.
- Estimate what it will cost / pick models → [Cost Planning](https://cortexdb.ai/docs/operations/cost-planning). Recommended models (text-embedding-3-small, gpt-4o-mini, gpt-5.6-terra, gpt-5.6-luna), per-event and per-answer costs, monthly estimates.
- See what the LLM lanes actually cost → [Token & Cost Ledger](https://cortexdb.ai/docs/operations/usage-ledger). `GET /v1/admin/usage`; set `CORTEX_MODEL_PRICES` for GPT-5.6 models.
- Isolate customers on one server → [Multi-Tenancy](https://cortexdb.ai/docs/enterprise/multi-tenancy). Tenant = token audience, the `cloud_shared_saas` preset.
- Back up or restore → [Backups & DR](https://cortexdb.ai/docs/enterprise/backups-dr). Cold backup of the data directory. [Export](https://cortexdb.ai/docs/api-reference/export) is a per-scope JSONL dump, not a backup.

## Start here

- [CortexDB for AI coding agents](https://cortexdb.ai/docs/coding-agents): drop-in rules block, the MCP server, and machine-readable docs so Claude Code / Codex / Grok / Hermes / OpenClaw generate correct CortexDB code.
- [Self-Hosting Quickstart](https://cortexdb.ai/docs/self-hosting/quickstart): one `docker run` to a running server on localhost:3141, then first write + recall (curl / Python / TypeScript).
- [Upgrading](https://cortexdb.ai/docs/self-hosting/upgrading): image swap with a 120 s graceful stop, what each release changes for an existing deployment, rollback, and client/connector upgrade notes.
- [What is CortexDB?](https://cortexdb.ai/docs): overview, key advantages, access surfaces.
- [Getting Started](https://cortexdb.ai/docs/quickstart): run a server, then [Python Quickstart](https://cortexdb.ai/docs/quickstart/python) · [TypeScript Quickstart](https://cortexdb.ai/docs/quickstart/typescript).

## Essentials for agents

- SDK package is `cortexdbai` (Python + TypeScript), NOT `cortexdb`. CLI: `cortexdb-cli`. MCP: `cortexdb-mcp`.
- Client: `V1Client(api_url="http://localhost:3141", actor="user:local")`. Dev auth: start the server with `CORTEX_INSECURE_NO_AUTH=1` (no token); otherwise set `CORTEX_API_KEY` and pass it as the bearer.
- Write: `client.experience(scope, text=..., role="user", observed_at=..., idempotency_key=...)` — `modality` is optional: taken from `source=` if set, else `conversation`.
- Read: `client.recall(scope, view="holistic", query=..., include=["events","facts","beliefs","episodes"], diagnostics="none")`; use `pack["context_block"]`.
- Q&A: `client.answer(scope, question=..., diagnostics="none")` — the field is `question`, not `query`.
- Fact fields: `fact["id"]`, `fact["subject"]["id"]`, `fact["object"]["value"]` — never `fact["fact_id"]` / `fact["subject"]["name"]`.
- On a content-only self-host, Facts/Beliefs/Understanding are empty and `/v1/answer` is disabled until enrichment / the answer lane is configured; events + vector recall work by default.

## SDKs & clients

- [Python SDK](https://cortexdb.ai/docs/sdks/python): V1Client / AsyncV1Client, methods, exception hierarchy.
- [TypeScript SDK](https://cortexdb.ai/docs/sdks/typescript): V1Client, camelCase fields, typed errors.
- [CLI](https://cortexdb.ai/docs/sdks/cli): the `cortexdb` command; `cortexdb-sync` for connectors.
- [REST API](https://cortexdb.ai/docs/sdks/rest-api): direct HTTP with curl.
- [MCP Server](https://cortexdb.ai/docs/sdks/mcp-server): expose CortexDB to Claude Code / Cursor / VS Code.

## Core concepts

- [The Five Memory Layers](https://cortexdb.ai/docs/concepts/layers) · [Event Sourcing](https://cortexdb.ai/docs/concepts/event-sourcing) · [Bi-temporal](https://cortexdb.ai/docs/concepts/bi-temporal)
- [Scopes](https://cortexdb.ai/docs/concepts/scopes) · [Experience Envelope](https://cortexdb.ai/docs/concepts/experience-envelope) · [Lifecycle](https://cortexdb.ai/docs/concepts/lifecycle)
- [Authorization](https://cortexdb.ai/docs/concepts/authorization) · [Knowledge Graph](https://cortexdb.ai/docs/concepts/knowledge-graph) · [Hybrid Retrieval](https://cortexdb.ai/docs/concepts/hybrid-retrieval)

## API reference (v1)

- [POST /v1/experience](https://cortexdb.ai/docs/api-reference/experience) · [POST /v1/recall](https://cortexdb.ai/docs/api-reference/recall) · [POST /v1/answer](https://cortexdb.ai/docs/api-reference/answer) · [POST /v1/compose](https://cortexdb.ai/docs/api-reference/compose) · [POST /v1/forget](https://cortexdb.ai/docs/api-reference/forget)
- [Events](https://cortexdb.ai/docs/api-reference/events) · [Facts](https://cortexdb.ai/docs/api-reference/facts) · [Beliefs](https://cortexdb.ai/docs/api-reference/beliefs) · [Episodes](https://cortexdb.ai/docs/api-reference/episodes) · [Understanding](https://cortexdb.ai/docs/api-reference/understanding)
- [Claims & Conflicts](https://cortexdb.ai/docs/api-reference/claims-conflicts): the bi-temporal record store — point/interval claim queries and the conflict queue.
- [Scopes](https://cortexdb.ai/docs/api-reference/scopes) · [Auth](https://cortexdb.ai/docs/api-reference/auth) · [Admin](https://cortexdb.ai/docs/api-reference/admin) · [Erasures](https://cortexdb.ai/docs/api-reference/erasures) · [Audit](https://cortexdb.ai/docs/api-reference/audit) · [Derivation status](https://cortexdb.ai/docs/api-reference/derivation-status) · [Error codes](https://cortexdb.ai/docs/api-reference/errors)
- Writes are async: poll [GET /v1/derivation/status](https://cortexdb.ai/docs/api-reference/derivation-status) (or write with `?wait=consolidated`; `?wait=indexed` covers BM25/HNSW indexing only) before relying on derived layers.

## Self-hosting & operations

- [Self-Hosting overview](https://cortexdb.ai/docs/self-hosting) · [Defaults & prerequisites](https://cortexdb.ai/docs/self-hosting/defaults)
- [Configuration](https://cortexdb.ai/docs/operations/configuration) · [Embeddings](https://cortexdb.ai/docs/operations/embeddings) · [LLM & Answer](https://cortexdb.ai/docs/operations/llm-answer) · [Profiles](https://cortexdb.ai/docs/operations/profiles) · [Security & Compliance](https://cortexdb.ai/docs/operations/security-compliance)
- [Recall Tuning](https://cortexdb.ai/docs/operations/recall-tuning) · [Admin Console](https://cortexdb.ai/docs/operations/admin-console): the operator UI built into the binary, served at `/` on the API port.
- [Retention & WAL](https://cortexdb.ai/docs/operations/retention-wal): per-scope expiry rules, dry-run sweeps, WAL census and compaction · [Token & Cost Ledger](https://cortexdb.ai/docs/operations/usage-ledger): GET /v1/admin/usage, durable per-role tokens and dollars · [Cost Planning](https://cortexdb.ai/docs/operations/cost-planning): recommended models and estimated spend.

## Enterprise

- [Multi-Tenancy](https://cortexdb.ai/docs/enterprise/multi-tenancy): tenant = token `aud`; on-prem multi-tenant deployments use the `cloud_shared_saas` isolation preset, not `on_prem_enterprise`.
- [Enterprise Security](https://cortexdb.ai/docs/enterprise/security) · [Deployment Presets](https://cortexdb.ai/docs/enterprise/deployment-presets) · [Audit Trail](https://cortexdb.ai/docs/enterprise/audit-trail) · [Backups & DR](https://cortexdb.ai/docs/enterprise/backups-dr)

## Integrations & connectors

- [Integrations overview](https://cortexdb.ai/docs/integrations): 31 framework recipes + 6 inference backends. E.g. [LangChain](https://cortexdb.ai/docs/integrations/langchain), [LlamaIndex](https://cortexdb.ai/docs/integrations/llamaindex), [Ollama](https://cortexdb.ai/docs/integrations/ollama).
- [Connectors overview](https://cortexdb.ai/docs/connectors): 18 self-hosted `cortexdb-sync` connectors (Slack, GitHub, Jira, Notion, …).

## Optional

- [llms-full.txt](https://cortexdb.ai/llms-full.txt): every documentation page concatenated into one file.