cortexdbai

TypeScript / JavaScript client for CortexDB — the long-term memory layer for AI systems.

Zero dependencies. Uses native fetch. Ships ESM + CJS with full TypeScript types. Works in Node 18+, Deno, Bun, browsers, edge runtimes — anywhere fetch + AbortController exist.

npm install cortexdbai

Three-line quickstart (recommended)

import { V1Client } from "cortexdbai/v1";

// Anonymous signup against the public SaaS — no email, no card, 7-day token.
const client = await V1Client.signup();

await client.experience(client.actor, {
  text: "Q3 revenue exceeded $2.4M, up 34% YoY",
  observedAt: new Date().toISOString(),
  idempotencyKey: "q3-update-001",
});

const pack = await client.recall(client.actor, {
  query: "What was Q3 revenue?",
  diagnostics: "none",
});
console.log(pack.context_block);
// => "Q3 revenue exceeded $2.4M, up 34% YoY [1]"

V1Client.signup() POSTs to https://api-v1.cortexdb.ai/v1/auth/signup, gets a PASETO bearer + actor + default scope, and returns a fully-wired client. The token has a 7-day TTL on the free tier.

Explicit construction (when you already have a token)

import { V1Client } from "cortexdbai/v1";

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

The actor passed to the constructor (or to signup) is sent as X-Cortex-Actor on every request — the v1 API requires it alongside the bearer token.

What you can do

// Store
await client.experience(scope, { text: "…", observedAt, idempotencyKey });
await client.experienceBulk(scope, [/* envelopes */]);

// Retrieve
const pack = await client.recall(scope, { query, view: "holistic" });
const ans  = await client.answer(scope, { question, view: "holistic" });

// Layer reads
await client.events(scope, { view: "local", limit: 50 });
await client.episodes(scope, "local");
await client.facts(scope);
await client.beliefs(scope);
await client.understanding(scope);

// Forget (audited)
await client.forget(scope, { selector: { memory_ids: ["evt_…"] }, audit_note: "…" });

// Auth + admin
const me = await client.whoami();
await client.mintToken({ subject: "user:alice", ttlSeconds: 3600, scopes: [scope] });

Full method-by-method reference: https://cortexdb.ai/docs/sdks/typescript

Typed errors

import {
  V1Error,
  V1AuthError,
  V1PolicyDeniedError,
  V1RateLimitError,
  V1NotConfiguredError,
  V1ConnectionError,
  V1TimeoutError,
} from "cortexdbai/v1";

try {
  await client.experience(scope, { ... });
} catch (e) {
  if (e instanceof V1PolicyDeniedError) {
    console.error(`denied by ${e.tier}: ${e.capability}`);
  } else if (e instanceof V1RateLimitError) {
    await new Promise(r => setTimeout(r, 1000));
  } else {
    throw e;
  }
}

Types

import type {
  StratifiedPack,
  AnswerResponse,
  ExperienceItem,
  RecallParams,
  AnswerParams,
  ForgetParams,
  Citation,
  Provenance,
  Diagnostics,
} from "cortexdbai/v1";

tsc --noEmit reports zero errors against the v1 surface.

Which import should I use?

import { CortexDB } from "cortexdbai";       ← the v1 client (recommended)
import { V1Client } from "cortexdbai/v1";    ← same class, explicit name

Both names resolve to the same v1 client — CortexDB is an alias of V1Client. It targets the production HTTP surface (POST /v1/experience, /v1/recall, /v1/answer, PASETO auth, hierarchical scopes). The pre-0.3 v0 client (/v1/remember, /v1/search, no actor header) was retired in 0.3.0; pin cortexdbai@<0.3 only if you still depend on it.

See also

• TypeScript quickstart
• Authorization concepts
• Experience envelope
• Stratified pack

License

Apache-2.0