You're reading the v2.0.0 docs. View the latest (v2.2.0) →

TypeScript SDK quickstart — first query in 5 minutes

This page walks through installing the TypeScript SDK, connecting to a local Relata server, and running your first governed query + search + memory recall.

Prerequisites

  • Node.js 18+ (or Deno / Bun)
  • A running Relata server (cargo run -p relata-cli -- serve)

Verify the server is up:

curl http://127.0.0.1:9090/health
# {"status":"ok",...}

1. Install

npm install @zysec-ai/relata-sdk
# or
yarn add @zysec-ai/relata-sdk
# or
bun add @zysec-ai/relata-sdk

2. Connect and insert a row

import { createClient } from "@zysec-ai/relata-sdk";
 
const relata = createClient("http://localhost:9090", {
  defaultPurpose: "analytics",          // required — every query must declare a purpose
  bearerToken: process.env.RELATA_TOKEN, // required when server sets RELATA_BEARER_TOKEN
});
 
// Insert (governed — purpose is recorded in the audit log).
await relata.query(
  "INSERT INTO Person (_pk, name, email) VALUES ('p1', 'Alice', 'alice@example.com')",
);

3. Query it back

const result = await relata.query("SELECT * FROM Person LIMIT 5");
for (const row of result.rows) {
  console.log(row.name, row.email);
}

4. Full-text + hybrid search

const hits = await relata.search({
  query: "alice",
  type: "Person",
  limit: 5,
  highlight: true,
  matchingStrategy: "all",   // 'any' | 'all' | 'last' | 'frequency'
});
 
for (const hit of hits.hits) {
  console.log(hit.score, hit.fields["name"], hit.highlights);
}

5. Agent memory

await relata.remember("Alice prefers dark mode", { purpose: "agent-notes" });
const memories = await relata.recall("ui preferences", { topK: 3 });

6. Cypher

Relata auto-detects Cypher — send a MATCH query through relata.query():

const result = await relata.query(
  "MATCH (n:Person {id: 'p1'}) RETURN *",
);
// → SELECT * FROM Person WHERE id = 'p1'

Authentication & multi-tenant

const relata = createClient("http://localhost:9090", {
  bearerToken: process.env.RELATA_TOKEN,
  defaultPurpose: "analytics",
  tenant: "org-acme",   // X-Organization-Id (multi-tenant)
  timeoutMs: 15_000,
});

Runtime compatibility

The TS SDK uses native fetch with zero runtime dependencies. Works in:

  • Node.js 18+
  • Deno
  • Bun
  • Modern browsers (Chrome, Firefox, Safari, Edge)
  • Cloudflare Workers / Vercel Edge Functions

Examples

The TypeScript SDK ships a parallel set of runnable examples in sdks/typescript/examples/. Run any of them with Node 23+ (--experimental-strip-types), Deno, or Bun:

# Basic + ecosystem
RELATA_TOKEN=secret node --experimental-strip-types examples/basic-query.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/ingest.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/advanced-query.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/governance.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/memory-quickstart.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/multi-tenant.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/ephemeral-server.ts
 
# Domain operators
RELATA_TOKEN=secret node --experimental-strip-types examples/graphql.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/graph-algorithms.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/intelligence.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/multi-search.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/parameterized.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/lookups.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/streaming.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/a2a.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/tokens.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/tenant-admin.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/bitemporal.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/audit.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/analytics.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/jobs-workflows.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/face-search.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/investigation.ts

Next steps