CortexDB for AI Coding Agents

Make Claude Code, Codex, Grok, Hermes, OpenClaw and other AI coding assistants use CortexDB correctly — a drop-in rules file, the MCP server, and machine-readable docs.

If you build with an AI coding assistant — Claude Code, OpenAI Codex, Grok, Hermes, OpenClaw, Cursor, and the like — the fastest way to add CortexDB is to give the agent the right context so it generates correct code the first time. This page gives you three ways to do that, easiest first.

What agents get wrong without context

Left to guess, coding assistants reliably make the same handful of mistakes: they install the wrong package (cortexdb instead of cortexdbai), pass a modality= argument older SDKs don't take, and read fact["fact_id"] / fact["subject"]["name"] (the real fields are fact["id"] / fact["subject"]["id"]). The rules block below eliminates all of them.

Option 1 — The MCP server (Claude Code, Cursor, VS Code)

The most seamless path: run the CortexDB MCP server and the agent gets memory tools (memory_store, memory_search, …) directly — no code to write.

# Claude Code, pointed at a self-hosted server:
claude mcp add --transport stdio \
  -e CORTEXDB_URL=http://localhost:3141 \
  -e CORTEXDB_ACTOR=user:local \
  -e CORTEXDB_SCOPE=org:demo/user:local \
  cortexdb -- cortexdb-mcp

For a keyed server add -e CORTEXDB_API_KEY=<your secret>. Cursor, Windsurf, and VS Code use the same binary via a JSON config — see the MCP Server page.

Option 2 — A drop-in rules file (any agent)

Coding agents read a conventions file from your repo: Claude Code reads CLAUDE.md, Codex and most others read AGENTS.md. Paste this block into that file (or your agent's system prompt) and it will use CortexDB correctly:

## Using CortexDB (long-term memory for AI agents)

- SDK install: `pip install cortexdbai` (Python) or `npm install cortexdbai` (TypeScript).
  Do NOT install `cortexdb` — that is an unrelated package. CLI: `pip install cortexdb-cli`.
- Imports: Python `from cortexdb.v1 import V1Client`; TypeScript `import { V1Client } from "cortexdbai/v1"`.
- Prefer self-hosting. Install with the customer portal's installer (`/install.sh`, it verifies a
  write and a recall), or by hand: load the image from customer.cortexdb.ai, then start a local dev
  server (no token needed) with the company license:
    docker run -d -p 127.0.0.1:3141:3141 -v cortexdb-data:/data -e CORTEX_LICENSE \
      -e CORTEX_INSECURE_NO_AUTH=1 -e CORTEX_EMBEDDING_API_KEY=$OPENAI_API_KEY cortexdb/cortexdb:v0.12.8
  For a secured/shared server, drop CORTEX_INSECURE_NO_AUTH, set CORTEX_API_KEY=<secret>, and pass it as
  `Authorization: Bearer <secret>`. A keyless, network-exposed server auto-generates a key and requires it.
- Construct the client:
    client = V1Client(api_url="http://localhost:3141", actor="user:local")   # bearer=<key> if keyed
- scope is a hierarchical `type:name` path, e.g. "org:acme/user:alice".
- Write memory: client.experience(scope=scope, text="...", role="user",
      observed_at="<ISO-8601>", idempotency_key="<stable-key>", wait="indexed")
  Don't pass `modality=` unless you need a non-default label: it defaults to `conversation`, and the keyword
  only exists from cortexdbai 0.11.2 (older versions raise TypeError). The raw REST body DOES take `modality`.
- Read memory: pack = client.recall(scope=scope, view="holistic", query="...",
      include=["events","facts","beliefs","episodes"], diagnostics="none")
  Use pack.get("context_block", ""). Views: raw | granular (alias local) | holistic | descend | lineage | structured.
- Q&A with citations: client.answer(scope=scope, question="...", diagnostics="none")
  The field is `question`, not `query`.
- Fact fields are: fact["id"], fact["subject"]["id"], fact["object"]["value"] — there is NO fact["fact_id"]
  and no fact["subject"]["name"]. Belief/episode/etc. ids are also keyed as "id".
- On a default self-host (content-only) the Facts/Beliefs/Understanding layers are EMPTY and /v1/answer is
  disabled until enrichment / the answer lane (CORTEX_ANSWER_*) is configured. events + vector recall work.
- Writes return `captured` (~10 ms, WAL append) BEFORE extraction; pass wait="indexed" for read-after-write.
- Full docs: https://cortexdb.ai/docs  ·  machine index: https://cortexdb.ai/llms.txt

On CortexDB Cloud

Replace the self-hosting lines with your cloud account: construct the client with api_url="https://api.cortexdb.ai", actor="user:acct_<id>" and bearer=<your API token> (from your dashboard), and keep every scope under org:acct_<id>/. On the cloud, enrichment and /v1/answer are on, and every request counts against your plan: past a limit the server answers 402 PLAN_LIMIT_REACHED, and 429 SUBTREE_RATE_LIMITED means wait Retry-After seconds.

Why this works

Every line above is a correction for a mistake real agents make, drawn from the same verification that produced these docs. Keeping it in AGENTS.md / CLAUDE.md means the agent re-reads it every session.

Option 3 — Point the agent at the docs

The whole doc set is published in an LLM-friendly form:

https://cortexdb.ai/llms.txt — a curated index (titles + one-line descriptions + links) an agent can crawl to find the right page.
https://cortexdb.ai/llms-full.txt — every page concatenated into one file, for pasting the entire reference into a long-context model.

Tell your agent: "Use CortexDB. Read https://cortexdb.ai/llms.txt for the docs."

Task router

llms.txt opens with a by-task block so an agent can resolve a task to the one page that answers it without reading the corpus. The same routes, for humans:

I want to…	Read this page	Why this one
Run a server on my machine	Self-Hosting Quickstart	One `docker run`, first write and recall. The overview is orientation; Defaults is what is off by default.
Store a memory	POST /v1/experience	Required fields, `?wait=` modes, idempotency, bulk. The envelope concept explains the shape, not the request.
Get context for a prompt	POST /v1/recall	Views, `include`, budgets, `context_block`. Recall Tuning is the env knobs.
Ask a question, get a cited answer	POST /v1/answer	Self-hosted, the answer lane is opt-in: configure it per LLM & Answer first.
Delete one person's data (GDPR)	Erasures	The selector-driven path that removes WAL rows (retention sweeps also remove them by age). `/v1/forget` is selective, not erasure.
Remove something stored by mistake	POST /v1/forget	Preview, then execute with `from_preview_id`; audited.
Understand request authentication	Authorization	`CORTEX_API_KEY` as bearer, `CORTEX_INSECURE_NO_AUTH=1` for loopback dev. Minting tokens is Auth.
Name scopes for a tenant or app	Scopes	`type:id` segments, allowed types. Registering them is /v1/scopes.
Facts / Beliefs are empty	Defaults & prerequisites	Enrichment is opt-in on self-host. If it is on and layers lag, poll Derivation status.
Change the embedding model	Embeddings	The pin, why a dimension change is refused, the offline `CORTEX_EMBEDDING_REBUILD_VECTORS` migration.
Give Claude Code / Cursor memory	MCP Server	Install, per-client config, env vars, tool list.
Sync Slack, Jira, GitHub, Notion	Connectors	`cortexdb-sync`, `--scope-template`, credentials; then the per-source page.
Expire old data / reclaim WAL space	Retention & WAL	Per-scope rules, dry-run sweeps, compaction.
Ingest PDFs, images, audio	Media Ingestion	Upload a blob and reference it with its text (`content.transcript`).
Index a code repository	Code Plane	`CORTEX_CODE_PLANE=1`, mount the repo, `/v1/code/*`.
Estimate cost / pick models	Cost Planning	Recommended models, per-event and per-answer costs, monthly estimates.
See what the LLM lanes actually cost	Token & Cost Ledger	`GET /v1/admin/usage`; set `CORTEX_MODEL_PRICES` for GPT-5.6 models.
Isolate customers on one server	Multi-Tenancy	Tenant = token audience, `cloud_shared_saas` preset.
Back up or restore	Backups & DR	Cold backup of the data directory. Export is a per-scope JSONL dump, not a backup.

Per-agent notes

Agent	Recommended path
Claude Code	MCP server (`claude mcp add`, Option 1) or a `CLAUDE.md` rules block (Option 2).
OpenAI Codex	`AGENTS.md` rules block (Option 2).
Grok	Paste the rules block into context, or point it at `llms.txt` (Option 3).
Hermes	Use the Hermes integration (`CortexDBMemoryProvider`) for runtime memory; the rules block helps the coding agent wire it.
OpenClaw	Use the OpenClaw recipe (SDK/REST); rules block for correct calls.
Cursor / Windsurf / VS Code	MCP server (Option 1).

A correct starting snippet

If you'd rather hand the agent working code to adapt:

from cortexdb.v1 import V1Client

client = V1Client(api_url="http://localhost:3141", actor="user:local")   # dev: CORTEX_INSECURE_NO_AUTH=1
scope = "org:acme/user:alice"

client.experience(
    scope=scope,
    text="User prefers Python over JavaScript.",
    role="user",
    observed_at="2026-05-16T10:42:00Z",
    idempotency_key="pref-001",
    wait="indexed",
)

pack = client.recall(scope=scope, view="holistic",
                     query="What language does the user prefer?", diagnostics="none")
print(pack.get("context_block", ""))