TypeScript SDK

The SDK wraps the REST + MCP endpoints in apps/edge and the WebSocket subscribe stream. Works in Node 20+, Bun, Deno, browsers, and Cloudflare Workers.

Install

pnpm add @memoturn/sdk

Construct

import { Memoturn } from "@memoturn/sdk";

const mt = new Memoturn({
  apiKey: process.env.MEMOTURN_API_KEY!,
  projectId: "my-project",
});

Identity (the email stamped on every recorded turn) is bound to the API key at mint time on the dashboard — no per-request identity to pass. If you need attribution from multiple humans, mint one key per human.

Optional overrides: baseUrl (default https://api.memoturn.ai), wsUrl (defaults to wss:// form of baseUrl), fetch (provide a custom fetch — e.g. for service-binding tests).

Record a turn

const result = await mt.recordTurn({
  role: "user",
  content: "deploying the worker tonight",
  session_id: "sprint-42",
});
// → { ok: true, turn_id: "01H…", deduped: false }

Pass client_turn_id to make retries idempotent — the same id always returns the same turn_id even if your worker restarts mid-write.

Search

const { hits } = await mt.searchMemory({ query: "deploy the worker", k: 5 });
for (const h of hits) {
  console.log(h.score, h.source.mode, h.content);
}

Modes (auto / chunks / summaries / entities / code) shape the retrieval — see Quickstart §2.

Subscribe to live activity

const ac = new AbortController();
setTimeout(() => ac.abort(), 60_000);

for await (const event of mt.subscribe({ signal: ac.signal })) {
  if (event.kind === "consolidation_completed") {
    console.log("summary written:", event.payload);
  }
}

The iterable yields typed BroadcastEvent objects. Filter server-side with subscribe({ kinds: ["turn_recorded"] }) to cut volume.

Pin and forget

const { memory } = await mt.pinMemory({
  content: "deploy uses GH Actions; staging is CI-only",
  tags: ["ops", "ci"],
});

await mt.forgetMemory(memory.id);

Summarize on demand

const out = await mt.summarizeSession({ session_id: "sprint-42", force: true });
// { ok: true, memory_id: "01H…", turns_compressed: 23, from_at, to_at }
// or { ok: false, reason: "no_new_turns" }

Error handling

All errors are MemoturnError with status (HTTP) and data (server-provided detail). The error envelope is JSON-RPC compliant under the hood, so MemoturnError.status is the HTTP code and data carries the JSON-RPC error.data field when present.