TypeScript SDK

The official TypeScript SDK for CortexDB. Fully typed, supports Node.js 18+ and modern browsers (via fetch). Zero runtime dependencies.

Installation

npm install @cortexdb/client

Client Initialization

import { CortexDB } from "@cortexdb/client";

const cortex = new CortexDB({
  baseUrl: "http://localhost:3141",  // CortexDB server URL
  apiKey: "your-api-key",            // API key for authentication
  timeout: 30_000,                    // Request timeout in ms
  maxRetries: 3,                      // Retry count for transient errors
});

Environment Variables

// Reads CORTEXDB_API_KEY from process.env
const cortex = new CortexDB();

Methods Reference

cortex.remember()

Store a piece of information in CortexDB.

const result = await cortex.remember(
  "We decided to migrate to CockroachDB for payments.",  // content
  "default",                  // tenantId (optional, default "default")
  "engineering",              // scope (optional)
  { team: "infra" },         // metadata (optional)
);

Returns: RememberResponse

interface RememberResponse {
  id: string;        // Assigned ID
  status: string;    // Status
}

cortex.recall()

Retrieve relevant memories matching a natural-language query.

const results = await cortex.recall(
  "What database are we using for payments?",  // query
  "default",          // tenantId (optional, default "default")
  4096,               // maxTokens (optional, default 4096)
  0.0,                // minConfidence (optional, default 0.0)
);

Returns: RecallResponse

interface RecallResponse {
  matches: RecallMatch[];
  total: number;
}

interface RecallMatch {
  content: string;
  confidence: number;
  episodeId?: string | null;
  metadata?: Record<string, unknown> | null;
}

cortex.forget()

Delete memories matching a query.

const result = await cortex.forget(
  "payments migration",       // query (optional)
  "Decision reversed",        // reason (optional, default "")
  "default",                  // tenantId (optional, default "default")
);

Returns: ForgetResponse

interface ForgetResponse {
  deleted: number;     // Number of records deleted
  status: string;
}

cortex.search()

Search across memories and episodes with filters.

const results = await cortex.search(
  "authentication issues",     // query
  {                             // filters (optional)
    source: "slack",
    episodeType: "message",
    timeRange: "7d",
    namespace: "engineering",
  },
  20,                           // limit (optional, default 20)
  0,                            // offset (optional, default 0)
  "default",                    // tenantId (optional, default "default")
);

Returns: SearchResponse

interface SearchResponse {
  context: string;
  confidence: number;
  latencyMs: number;
  episodes: EpisodeBrief[];
  totalEpisodes: number;
}

cortex.entity()

Get detailed information about a specific entity.

const entity = await cortex.entity(
  "ent_abc123",        // entityId
  "default",            // tenantId (optional)
);

Returns: EntityResponse

interface EntityResponse {
  id: string;
  name: string;
  entityType: string;
  firstSeen: string;
  lastSeen: string;
  episodeCount: number;
  relationships: EntityRelationship[];
  recentEpisodes: EpisodeBrief[];
}

cortex.link()

Create an explicit relationship between two entities.

const result = await cortex.link(
  "ent_123",              // sourceEntityId
  "ent_456",              // targetEntityId
  "DEPENDS_ON",           // relationship
  "Payments depends on Redis for caching",  // fact (optional, default "")
  0.9,                    // confidence (optional, default 0.9)
  "default",              // tenantId (optional, default "default")
);

Returns: LinkResponse

interface LinkResponse {
  id: string;
  createdAt: string;
}

cortex.ingestEpisode()

Ingest a structured episode.

import { EpisodeType, ActorType } from "@cortexdb/client";

const result = await cortex.ingestEpisode({
  content: "Deploy succeeded at 14:32 UTC.",
  type: EpisodeType.EVENT,
  tenantId: "default",
  actor: { id: "ci-bot", name: "CI Bot", type: ActorType.SERVICE },
  source: { system: "github-actions" },
  metadata: { commit: "abc123" },
});

Returns: IngestEpisodeResponse

interface IngestEpisodeResponse {
  id: string;
  status: string;
}

cortex.listEpisodes()

List episodes with optional filtering.

const result = await cortex.listEpisodes(
  "default",    // tenantId (optional)
  0,             // offset (optional)
  50,            // limit (optional, default 50)
);

Returns: ListEpisodesResponse

interface ListEpisodesResponse {
  episodes: Episode[];
  total: number;
  offset: number;
  limit: number;
}

cortex.health()

const health = await cortex.health();
console.log(health.status);    // "ok"
console.log(health.version);   // Server version

cortex.metrics()

const metrics = await cortex.metrics();

Convenience Methods

cortex.memory()

One-liner alias for recall():

const result = await cortex.memory("why did checkout fail yesterday");

cortex.store()

Smart store that accepts a string or a structured object:

// String — delegates to remember()
await cortex.store("The deploy succeeded at 14:32 UTC.");

// Object — converts to IngestEpisodeRequest and delegates to ingestEpisode()
await cortex.store({
  content: "Deploy ok",
  type: "event",
  source: "ci",
});

cortex.context()

Retrieve enriched context for an LLM agent with a higher default token budget (8192):

const result = await cortex.context(
  "current status of payments",    // query
  "incident-bot",                   // agentId (optional)
  "default",                        // tenantId (optional)
  8192,                             // maxTokens (optional, default 8192)
);

Error Handling

import {
  CortexError,
  CortexAPIError,
  CortexAuthError,
  CortexRateLimitError,
  CortexConnectionError,
  CortexTimeoutError,
} from "@cortexdb/client";

try {
  await cortex.recall("test");
} catch (error) {
  if (error instanceof CortexRateLimitError) {
    console.log(`Retry after ${error.retryAfter}s`);
  } else if (error instanceof CortexAuthError) {
    console.log("Check your API key");
  } else if (error instanceof CortexAPIError) {
    console.log(`Error ${error.statusCode}: ${error.message}`);
  }
}

The client automatically retries on transient errors (429, 502, 503, 504) with exponential backoff.

All public methods accept an optional AbortSignal as their last parameter for request cancellation.

Next Steps