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 the SDK doesn'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 cortexdb cortexdb-mcp \
  -e CORTEXDB_URL=http://localhost:3141 \
  -e CORTEXDB_ACTOR=user:local

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. Start a local dev server (no token needed):
    docker run -d -p 127.0.0.1:3141:3141 -v cortexdb-data:/data \
      -e CORTEX_INSECURE_NO_AUTH=1 -e OPENAI_API_KEY=$OPENAI_API_KEY cortexdb/cortexdb:latest
  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")
  NEVER pass `modality=` to experience() — the SDK infers it. (The raw REST body DOES take a `modality` field.)
- 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

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."

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", ""))