@cortexdb/client

TypeScript SDK for CortexDB — The Long-Term Memory Layer for AI Systems.

Zero dependencies. Uses native fetch. Ships ESM + CJS with full TypeScript types.

Installation

npm install @cortexdb/client

Requires Node.js 18+ (native fetch support).

Quick Start

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

const cortex = new CortexDB({ baseUrl: "http://localhost:3141" });

// Store a memory
await cortex.remember("The deploy succeeded at 14:32 UTC.");

// Recall memories
const results = await cortex.recall("What happened with the deploy?");
console.log(results.matches);

Configuration

const cortex = new CortexDB({
  baseUrl: "http://localhost:3141", // default
  apiKey: "your-api-key",          // or set CORTEXDB_API_KEY env var
  timeout: 30000,                  // 30s default (milliseconds)
  maxRetries: 3,                   // retries on 429, 502, 503, 504
});

API Reference

Core Methods

remember(content, tenantId?, scope?, metadata?)

Store a piece of information.

const resp = await cortex.remember("Deploy v2.1 went live", "my-tenant", "deploys", {
  environment: "production",
});
// { id: "...", status: "stored" }

recall(query, tenantId?, maxTokens?, minConfidence?)

Retrieve relevant memories matching a query.

const results = await cortex.recall("latest deploy status", "my-tenant", 4096, 0.5);
for (const match of results.matches) {
  console.log(`[${match.confidence}] ${match.content}`);
}

forget(query?, reason?, tenantId?)

Delete memories matching a query.

const resp = await cortex.forget("old deploy logs", "Data retention policy", "my-tenant");
// { deleted: 12, status: "completed" }

ingestEpisode(episode)

Ingest a structured episode.

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

const resp = await cortex.ingestEpisode({
  content: "PR #142 merged by alice",
  tenantId: "my-tenant",
  type: EpisodeType.EVENT,
  actor: { id: "alice", name: "Alice", type: "human" },
  source: { system: "github" },
  metadata: { pr: 142 },
});

listEpisodes(tenantId?, offset?, limit?)

List episodes with pagination.

const page = await cortex.listEpisodes("my-tenant", 0, 25);
console.log(`${page.total} episodes total`);

health()

Check server health.

const h = await cortex.health();
// { status: "healthy", version: "0.1.0", uptimeSeconds: 3600 }

metrics()

Retrieve server metrics.

const m = await cortex.metrics();
console.log(`${m.episodeCount} episodes, ${m.storageBytes} bytes`);

Knowledge Graph Methods

entity(entityId, tenantId?)

Get detailed information about an entity.

const e = await cortex.entity("user:alice", "my-tenant");
console.log(e.relationships);

link(sourceEntityId, targetEntityId, relationship, fact?, confidence?, tenantId?)

Create a relationship between entities.

const resp = await cortex.link(
  "service:payments",
  "service:auth",
  "DEPENDS_ON",
  "Payments calls auth for token validation",
  0.95,
  "my-tenant",
);

search(query, filters?, limit?, offset?, tenantId?)

Search with filters.

const results = await cortex.search(
  "payment failures",
  { source: "slack", timeRange: "24h" },
  20,
  0,
  "my-tenant",
);

Convenience Methods

memory(query) — alias for recall

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

store(data) — smart dispatch

// String -> remember()
await cortex.store("The deploy succeeded.");

// Object -> ingestEpisode()
await cortex.store({
  content: "Deploy OK",
  type: "event",
  source: "ci",
  actor: "deploy-bot",
});

context(query, agentId?, tenantId?, maxTokens?) — recall with higher budget

const ctx = await cortex.context("current status of payments", "incident-bot");
// Uses 8192 max tokens by default

Cancellation

All methods accept an optional AbortSignal as the last parameter:

const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

const results = await cortex.recall("query", "default", 4096, 0.0, controller.signal);

Error Handling

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

try {
  await cortex.recall("test");
} catch (err) {
  if (err instanceof CortexRateLimitError) {
    console.log(`Rate limited. Retry after ${err.retryAfter}s`);
  } else if (err instanceof CortexAuthError) {
    console.log(`Auth failed: ${err.message}`);
  } else if (err instanceof CortexTimeoutError) {
    console.log(`Request timed out`);
  } else if (err instanceof CortexConnectionError) {
    console.log(`Cannot connect to server`);
  } else if (err instanceof CortexAPIError) {
    console.log(`API error ${err.statusCode}: ${err.message}`);
  }
}

License

MIT