TypeScript Quickstart

Get from zero to stored-and-retrieved memory in three lines with the TypeScript SDK.

Self-hosting? Point at your own server

The recommended way to run CortexDB is to host it yourself. Against a self-hosted dev server (started with CORTEX_INSECURE_NO_AUTH=1) you need no token — construct new V1Client({ apiUrl: "http://localhost:3141", actor: "user:local" }) and skip signup(). On a keyed server pass bearer: "<your CORTEX_API_KEY>". The cloud signup() path below is for the managed platform.

1. Install

npm install cortexdbai
# or: pnpm add cortexdbai / yarn add cortexdbai

The npm package is cortexdbai, not cortexdb. The bare cortexdb name on npm is a different, unaffiliated package — installing it will not give you this SDK. Always cortexdbai. (If your AI coding agent autocompletes cortexdb, correct it.)

Requires Node 18+ (or any runtime with fetch and AbortController).

2. The three-line path — `V1Client.signup()`

import { V1Client } from "cortexdbai/v1";

const client = await V1Client.signup();
await client.experience(client.actor, {
  text: "Just got off a call with Priya at Acme. They upgraded to 200 seats.",
  observedAt: new Date().toISOString(),
  idempotencyKey: "alice-chat-001",
});
const pack = await client.recall(client.actor, {
  query: "What did we decide about Acme?",
  diagnostics: "none",
});
console.log(pack.context_block);

signup() posts to /v1/auth/signup, gets a token + actor + scope, and returns a fully-wired client — works in browsers, Node, and edge runtimes, anywhere fetch exists. The token lives in memory on client; persist it yourself (cookie, localStorage, env var) to survive a restart:

const client = await V1Client.signup();
process.env.CORTEX_TOKEN = client.bearer!;
process.env.CORTEX_ACTOR = client.actor;
process.env.CORTEX_SCOPE = client.actor;   // default scope = actor

3. SDK call signatures

The TypeScript SDK takes camelCase fields and flattens common cases:

// Capture
await client.experience(scope, {
  text:           "Acme upgraded to 200 seats.",
  role:           "user",                      // optional, default "user"
  observedAt:     new Date().toISOString(),
  idempotencyKey: "alice-chat-002",
  labels:         ["acme", "renewal"],
});

// Recall
const pack = await client.recall(scope, {
  view:        "holistic",   // raw | granular (alias local) | holistic | descend | lineage | structured
  query:       "What did we decide?",
  include:     ["beliefs", "facts", "episodes"],
  budgets:     { max_tokens: 4000 },   // budgets use the wire (snake_case) names
  diagnostics: "none",                 // "summary" needs diagnostics.read (paid tier)
});

// Recall + LLM answer
const ans = await client.answer(scope, {
  question:    "Did Acme renew?",
  view:        "holistic",
  temporal:    { natural: "last 30 days" },
  diagnostics: "none",
});

The wire format (raw JSON POST /v1/experience accepts) uses snake_case and a nested content/context envelope — see the Experience Envelope reference if you're building a raw-fetch client.

4. Explicit auth (for permanent identities)

import { V1Client } from "cortexdbai/v1";

const client = new V1Client({
  apiUrl: "https://api-v1.cortexdb.ai",
  actor:  "user:[email protected]",
  bearer: process.env.CORTEX_TOKEN!,
});

const me = await client.whoami();
console.log(me.effective_capabilities);   // snake_case on the whoami response

For service accounts that mint additional tokens via POST /v1/auth/tokens, see the Auth API reference.

5. The `wait` parameter

Default is async — experience() returns 202 Accepted as soon as the WAL append succeeds. Pass wait to block until a later stage:

await client.experience(scope, { text: "...", observedAt: now, idempotencyKey: "k" },
  { wait: "indexed" });   // returns once BM25 + HNSW have the event

Accepted values: "accepted" (alias for the omitted default) · "captured" · "indexed" · "consolidated" (30 s ceiling). For longer waits use GET /v1/lifecycle/stream?event_id=….

6. Inspecting derived layers

const facts    = await client.facts(scope);
const beliefs  = await client.beliefs(scope);
const concepts = await client.understanding(scope);

Facts populate within ~5–30 s of a write (requires enrichment configured — see Self-hosting defaults); Beliefs/Understanding are eventually consistent. Use Facts for read-after-write sanity checks.

What's next

Cancellation + timeouts

const client = new V1Client({
  apiUrl:    "https://api-v1.cortexdb.ai",
  actor:     "user:alice",
  bearer:    process.env.CORTEX_TOKEN!,
  timeoutMs: 30_000,
});

// Supply your own fetch (tracing, retries):
new V1Client({ apiUrl: "...", actor: "user:alice", fetch: myInstrumentedFetch });

On this page