TypeScript Quickstart

This guide gets you from zero to working memory in under 5 minutes using the TypeScript SDK.

Prerequisites

• Node.js 18+
• A CortexDB instance (cloud or self-hosted)
• An API key

Installation

npm install @cortexdb/client

Or with your preferred package manager:

yarn add @cortexdb/client
pnpm add @cortexdb/client

Initialize the Client

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

const cortex = new CortexDB({
  baseUrl: "http://localhost:3141", // or your self-hosted URL
  apiKey: "your-api-key",
});

Remember

Store memories as simple strings with optional metadata.

// Remember a message
await cortex.remember(
  "The user prefers dark mode and wants email notifications only for critical alerts.",
  "my-app",                    // tenantId
  undefined,                    // scope
  { source: "chat", author: "user-456" },  // metadata
);

// Remember a decision
await cortex.remember(
  "We chose Next.js 15 for the frontend rewrite. Key factors: RSC support, Vercel deployment, team familiarity.",
  "my-app",
  undefined,
  { source: "meeting-notes", author: "tech-lead" },
);

For structured episodes, use ingestEpisode:

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

await cortex.ingestEpisode({
  content: "Refactored the auth middleware to support JWT and API key auth.",
  type: EpisodeType.CODE,
  tenantId: "my-app",
  actor: { id: "alice", name: "Alice", type: ActorType.HUMAN },
  source: { system: "github" },
  metadata: { repo: "acme/backend", pr: 1234 },
});

Or use the convenience store() method:

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

// Object → ingestEpisode()
await cortex.store({
  content: "Deploy ok",
  type: "event",
  source: "ci",
});

Recall

Retrieve memories with natural language queries.

const results = await cortex.recall(
  "What frontend framework are we using?",
  "my-app",
);

for (const match of results.matches) {
  console.log(`[${match.confidence.toFixed(2)}] ${match.content}`);
}

Search

Search with filters for more control.

const results = await cortex.search(
  "architectural decisions",
  { episodeType: "decision", timeRange: "30d" },  // filters
  10,              // limit
  0,               // offset
  "my-app",        // tenantId
);

console.log(results.context);
for (const ep of results.episodes) {
  console.log(`  [${ep.episodeType}] ${ep.contentPreview}`);
}

Forget

await cortex.forget(
  "old notification preferences",  // query
  "User updated preferences",       // reason
  "my-app",                          // tenantId
);

Working with Entities

// Get entity with relationships
const entity = await cortex.entity("ent_xyz789", "my-app");

console.log(`${entity.name} (${entity.entityType})`);
for (const rel of entity.relationships) {
  console.log(`  --${rel.relationship}--> ${rel.targetEntityId}`);
}

Error Handling

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

try {
  const results = await cortex.recall("test", "my-app");
} catch (error) {
  if (error instanceof CortexAuthError) {
    console.error("Invalid API key");
  } else if (error instanceof CortexRateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof CortexAPIError) {
    console.error(`API error [${error.statusCode}]: ${error.message}`);
  } else if (error instanceof CortexError) {
    console.error(`CortexDB error: ${error.message}`);
  }
}

Framework Examples

Express.js Middleware

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

const app = express();
const cortex = new CortexDB({ apiKey: process.env.CORTEXDB_API_KEY! });

app.post("/chat", async (req, res) => {
  const { userId, message } = req.body;

  // Recall relevant context
  const context = await cortex.recall(message, "my-app");

  // ... use context with your LLM
  // ... generate response

  // Remember the exchange
  await cortex.remember(message, "my-app", undefined, {
    source: "chat",
    author: userId,
  });

  res.json({ response: "..." });
});

Next Steps