SDKUpdated 2026-05-30

SDK Quickstart

Use RetainDB SDK v5 for user memory, company brain queries, sources, and agent tasks.

Install SDK v5:

bash

npm install @retaindb/sdk@latest

Create a client:

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

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

Use RetainDB for high-level memory and agent helpers. Use RetainDBClient when you need direct access to project, source, and company brain API modules.

User Memory

const user = db.user("user_123");

await user.remember("User prefers direct answers.");

const { context } = await user.getContext("How should I reply?");

Use user memory for personalization, preferences, history, and user-specific facts.

Session Memory

const session = db.user("user_123").session("chat_456");

await session.remember("User is setting up a Next.js API route.");

const { context } = await session.getContext("What are we building?");

Use session memory for temporary conversation or workflow state.

Company Brain

const client = RetainDBClient.fromEnv();

const result = await client.context.query({
  project: "production",
  query: "What does our billing runbook say about retries?",
  top_k: 8
});

console.log(result.context);

Use company brain queries for indexed sources such as docs, repos, URLs, files, and source-derived memories.

Sources

await client.sources.create("production", {
  name: "Billing Runbook",
  connector_type: "text",
  config: {
    content: "Billing retries happen automatically for 3 days before escalation."
  }
});

const sources = await client.sources.list("production");

Use source APIs when a backend, CLI, or agent needs to add or update company brain inputs without the dashboard.

One-Call Non-Streaming Turn

Use runTurn when you want the SDK to retrieve memory, call your generator, and store the last user message.

const turn = await user.runTurn({
  messages: [{ role: "user", content: "How should I set up auth?" }],
  generate: ({ messages }) => llm.chat({ messages })
});

For streaming, use getContext() before the stream and remember() after it finishes.

Agent Task Memory

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

await task.event({
  type: "decision",
  summary: "Use Stripe Checkout for v1."
});

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

Use agent task memory for decisions, tool results, failures, and handoffs across multiple agents.

Which Helper Should I Use?

Need	SDK surface
user preferences	`db.user(userId)`
conversation state	`db.user(userId).session(sessionId)`
company knowledge	`client.context.query(...)`
agent filesystem	`client.context.readFile(path, { project })`
source automation	`client.sources.*`
planner/builder/reviewer workflows	`db.agent(agentId).task(taskId)`
low-level memory API	`client.memory.*`
project/key administration	`client.projects.`, `client.keys.`

Next: User and session memory, Company Brain API, or Agent task API.

Was this page useful?

Your feedback helps us make the product easier to ship with.