TypeScript SDK

@loregpt/sdk is the official TypeScript client. It needs Node 18+, has zero runtime dependencies (it uses the platform's native fetch), and ships as ESM.

Install

npm install @loregpt/sdk

Usage

Create a client, write an event, and pack a context. The seq a write returns is the min_seq of a later pack — that's the read-your-writes guarantee.

// Adapted from clients/typescript/examples/hero.ts (compile-tested in CI).
import { LoreClient } from "@loregpt/sdk";

const lore = new LoreClient({ apiKey: process.env["LORE_API_KEY"] ?? "" });

const { runId } = await lore.createRun();
const { seq } = await lore.write({
  runId,
  agentId: "researcher",
  content: "Auth flow moved to v2 — PR #42 merged",
});

const pack = await lore.pack({
  runId,
  query: "current state of auth work",
  scopes: { team: "platform" }, // optional retrieval filter
  minSeq: seq,
  tokenBudget: 2000,
});

pack.coveredSeq; // ≥ seq once distilled; until then the write is in the raw tail — either way, reflected
pack.savedTokens; // token savings vs raw history — a coarse estimate; small packs may round to 0

The client exposes four methods:

createRun() — start a run; returns { runId, createdAt }.
write({ runId, agentId, content }) — append an event (pass content or an opaque payload); returns { eventId, seq }.
writeState({ runId, agentId, entity, predicate, value }) — write a working-memory fact through the low-latency lane, so a same-run reader sees it immediately; returns { eventId, seq }.
pack({ runId, query, minSeq?, scopes?, limit?, tokenBudget? }) — assemble a context pack; returns the pack text, its sources, and coveredSeq / freshnessLagMs.

Client options

new LoreClient(options) accepts:

Option	Default	Description
`apiKey`	required	Bearer key from `lore provision` or `lore keys create`.
`baseUrl`	`http://localhost:8080`	The Lore server URL.
`timeoutMs`	`30000`	Per-request timeout in milliseconds.
`headers`	—	Extra headers sent on every request.
`fetch`	global `fetch`	A custom `fetch` implementation (proxy, tests, a non-global runtime).

Errors

Every failure is a LoreError. Switch on the concrete class (or .code) rather than matching messages — narrow the one case you handle specially and let a generic branch cover the rest:

import { LoreError, MinSeqOutOfRangeError } from "@loregpt/sdk";

try {
  await lore.pack({ runId, query: "…", minSeq: seq });
} catch (err) {
  if (err instanceof MinSeqOutOfRangeError) {
    // the run hasn't reached that seq — re-check the seq you're passing
  } else if (err instanceof LoreError) {
    // unauthorized · not_found · model_mismatch · connection · … — err.code tells you which
  } else {
    throw err;
  }
}

The full code → class map is in the API reference.

For the exhaustive method and type reference, see the package on npm.

Install

Usage

Client options

Errors

On this page