Node.js SDK

@breeth/sdk — official TypeScript / Node.js client. Zero runtime deps, ESM + CJS, full TypeScript types.

@breeth/sdk is a thin TypeScript fetch wrapper around the Breeth REST API. Built for Node 18+, ESM + CJS dual build, zero runtime dependencies (uses the global fetch).

Install

npm install @breeth/sdk

Works with pnpm, yarn, bun the same way.

Quickstart

import { BreethClient } from '@breeth/sdk';

const client = new BreethClient({ apiKey: process.env.BREETH_API_KEY! });

// Write
await client.write({
  content: "Sridhar prefers async Rust over Go for IO-heavy services.",
  groupId: 'default',
  extractIntent: true,
});

// Retrieve
const hits = await client.retrieve({
  query: "What language does Sridhar prefer?",
  groupId: 'default',
  limit: 5,
});

console.log(hits.edges);

Constructor

new BreethClient({
  apiKey: string;            // required — ck_live_… from /app/api-keys
  baseUrl?: string;          // default 'https://api.thebreeth.com'
  fetch?: typeof fetch;      // override (testing / custom transport)
});

Methods

`client.write(opts)`

Write an episode. Returns the episode id and pipeline status.

const res = await client.write({
  content: "Decision: switching to gRPC for the inference service.",
  groupId: 'default',
  sourceDescription: 'api',
  extractIntent: false,
});
res.episode_name;     // 'api_1778…'
res.extracted.entities;
res.cogram?.mode;     // 'sync' | 'async'

Param	Type	Notes
`content`	`string`	The text to memorize.
`groupId`	`string?`	Defaults to `'default'`. Scopes the write to a graph partition.
`sourceDescription`	`string?`	Free-text label for where this episode came from.
`extractIntent`	`boolean?`	Opt-in heuristic+LLM intent extraction. See intents.

`client.retrieve(opts)`

Hybrid BM25 + vector + graph search. Returns ranked edges with attribution.

const res = await client.retrieve({
  query: "What did Sridhar say about gRPC?",
  groupId: 'default',
  limit: 10,
});
for (const e of res.edges) {
  console.log(e.fact, e.confidence);
}

`client.entity(name, opts?)`

"Tell me about X" — fetches narrative + edges + episodes for an entity (substring match on name, UUID also accepted).

const view = await client.entity("Sridhar", { mode: 'all', limit: 20 });

`client.groups(opts?)`

List graph partitions in the team scope.

const { groups, total } = await client.groups({ limit: 20 });

Graph reads

const ents = await client.graph.listEntities({ limit: 20 });
const edges = await client.graph.listEdges({ limit: 20 });
const eps = await client.graph.listEpisodes({ limit: 20 });
const details = await client.graph.nodeDetails(entityUuidOrName);

Error handling

Non-2xx responses throw BreethError:

import { BreethError } from '@breeth/sdk';

try {
  await client.write({ content: '' });
} catch (e) {
  if (e instanceof BreethError) {
    console.error(e.status);   // 422
    console.error(e.slug);     // 'validation_error'
    console.error(e.body);     // server response body
  }
}

Status	Meaning
`401`	`slug: 'invalid_token'` — API key invalid or revoked
`402`	Payment required — past-due subscription
`403`	Scope insufficient (e.g. retract on a `write`-only key)
`404`	Entity / episode not found
`422`	Validation error — see `body` for the offending field
`429`	Rate limit (per-team or per-group)

End-user (B2B2C) pass-through

If you're calling Breeth on behalf of your users (and want per-end-user attribution / rate limiting), pass endUserId per call:

await client.write({ content: '…' }, { endUserId: 'user-42' });

The SDK forwards it as X-End-User-Id. Server-side, Breeth tags writes and applies the end-user's rate budget.

TypeScript types

Every method is fully typed. Hover in your editor or import type directly:

import type {
  WriteResponse,
  RetrieveResponse,
  EntityResponse,
  GraphEntityListResponse,
  NodeDetailsResponse,
} from '@breeth/sdk';

License + source

MIT. Source: github.com/Gramies/cogram-sdk-node. Issues + PRs welcome.

Node.js SDK

On this page