@retaindb/sdk

TypeScript SDK for RetainDB, the memory bus for agentic systems.

Install

npm install @retaindb/sdk@latest

Agent Memory Bus

import { RetainDB } from "@retaindb/sdk";

const db = new RetainDB({
  apiKey: process.env.RETAINDB_API_KEY,
  project: "my-product",
});

const task = db.agent("planner").task("checkout-redesign");

await task.event({
  type: "decision",
  summary: "Use a two-step checkout and keep Stripe.",
  salience: "high",
});

const context = await task.context("What should the builder know?");

await task.handoff({
  toAgentId: "builder",
  summary: "Continue checkout implementation.",
  context: String(context.context || ""),
});

Remember Conversations

For product chats, send the whole turn and let RetainDB decide what is worth remembering.

await db.remember([
  { role: "user", content: "We use Qdrant now, not Pinecone." },
  { role: "assistant", content: "Got it. I will remember Qdrant is the memory backend." },
], {
  userId: "user_123",
  sessionId: "chat_456",
});

const memories = await db.user("user_123").searchMemory("memory backend");

For explicit facts, pass a string:

await db.remember("User prefers concise answers.", {
  userId: "user_123",
  memoryType: "preference",
});

Conversation remember uses /v1/memory/extract/session. Direct string remember uses /v1/memory.

Direct Client

import { RetainDBClient } from "@retaindb/sdk";

const client = new RetainDBClient({
  apiKey: process.env.RETAINDB_API_KEY,
  project: "my-product",
});

await client.memory.add({
  content: "User prefers concise answers.",
  user_id: "user_123",
  write_mode: "async",
});

const results = await client.memory.search({
  query: "user preferences",
  user_id: "user_123",
});

Memory Router

Use the Memory Router when you want RetainDB to sit in front of an OpenAI-compatible chat provider. It searches memory from the current turn plus recent conversation context, injects the best grounded memories into the system prompt, calls your provider, and can remember the completed user/assistant turn.

import { createMemoryRouter } from "@retaindb/sdk/router";

const router = createMemoryRouter({
  apiKey: process.env.RETAINDB_API_KEY,
  project: "my-product",
  providerBaseUrl: "https://api.openai.com",
  providerApiKey: process.env.OPENAI_API_KEY,
  userId: "user_123",
  sessionId: "chat_456",
  memoryProfile: "quality",
  memoryTopK: 8,
  remember: { enabled: true },
});

const response = await router.chatCompletions({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "What did we decide?" }],
});

console.log(response.trace);

The router preserves your existing system prompt, adds a Relevant RetainDB memory context: block, sends x-retaindb-memory-router: v1, and records trace fields such as memory latency, provider latency, memory count, injected characters, fallback reason, and whether the turn was remembered. Memory lookup is best-effort by default, so provider calls still work during a memory outage.

v5 Rename

SDK v5 is a hard RetainDB rename. Public Whisper* exports were removed. Use SDK v4 if you still need the old names while migrating.