@breeth/sdk

Official TypeScript / Node.js SDK for Breeth, the memory layer for agentic apps.

Thin wrapper around the Breeth REST API. Zero runtime dependencies. Works on Node 18+, modern browsers, Bun, Deno, and edge runtimes that expose fetch.

Install

npm install @breeth/sdk

Quickstart

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

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

// Write an episode.
await client.write({
  content: "Sarah passed the screen with strong Python signal. Priya is the recruiter.",
  groupId: "hr_screens",
});

// Hybrid semantic + graph retrieval.
const hits = await client.retrieve({
  query: "Who has Priya recently screened?",
  limit: 10,
});

// Pull the full neighborhood around a single graph node.
const detail = await client.graph.nodeDetails("Sarah");

Configuration

new BreethClient({
  apiKey: "ck_live_...",          // required
  baseUrl: "https://api.thebreeth.com", // default
  fetch: customFetch,             // optional, defaults to globalThis.fetch
});

For self-hosted Enterprise deployments, override baseUrl. For local development against the Breeth API server, set baseUrl to http://localhost:8000 (or wherever the API listens).

Per-request options

Every method accepts an optional second argument:

await client.write(
  { content: "..." },
  {
    endUserId: "user_42",  // forwarded as X-End-User-Id for B2B2C apps
    signal: abortController.signal,
  },
);

API reference

| Method | HTTP | Notes | | --- | --- | --- | | client.write({ content, groupId?, sourceDescription?, extractIntent? }) | POST /v1/episodes | Ingest a prose episode. extractIntent: true opts into intent extraction (counts against your team's intent cap). | | client.retrieve({ query, groupId?, limit? }) | POST /v1/search | Hybrid semantic + graph retrieval. Response fields use server aliases (_cache, _tier). | | client.entity(name, { mode?, limit? }) | GET /v1/entities/{name} | mode is one of "narrative", "edges", "episodes", "all". Default "narrative". | | client.groups({ query?, limit?, offset? }) | GET /v1/groups | List group_ids accessible to the caller. | | client.graph.nodeDetails(identifier) | GET /v1/graph/nodes/{identifier}/details | identifier is an entity UUID or name. | | client.graph.listEntities({ query?, limit?, offset? }) | GET /v1/graph/entities | | | client.graph.listEdges({ query?, limit?, offset?, includeRetracted? }) | GET /v1/graph/edges | | | client.graph.listEpisodes({ query?, limit?, offset? }) | GET /v1/graph/episodes | |

Error handling

Every non-2xx response throws a BreethError:

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

try {
  await client.retrieve({ query: "..." });
} catch (err) {
  if (err instanceof BreethError) {
    console.error(err.status, err.slug, err.body);
    if (err.slug === "quota_exceeded") {
      // handle quota wall
    }
  } else {
    throw err;
  }
}

Common slugs the API surfaces:

• payment_required (HTTP 402) — Stripe subscription past due or canceled.
• quota_exceeded (HTTP 429) — write, retrieval, or intent cap reached.

Design notes

This SDK is intentionally thin. There is no retry logic, no auto-pagination, no logging, no client-side rate limiting. Wrap as you wish in your application layer.

Streaming NDJSON endpoints (GET /v1/graph/nodes, GET /v1/graph/links) are not yet exposed by this SDK and are planned for v0.2.

Auth

API keys are issued from your Breeth dashboard at thebreeth.com. Use a ck_live_ key for production and a ck_test_ key for development. Keys resolve to a team server-side, so you do not need to send X-Cogram-Team-Id.

License

MIT. Copyright (c) 2026 Breeth.