5 Minute Quickstart

This quickstart teaches the core RetainDB loop for AI apps:

1. Remember something about a user.
2. Retrieve the right memory before the next model call.
3. Inject the context into an OpenAI-compatible chat request.

Install

npm install @retaindb/sdk@latest openai

Set your API key

Use a server-side environment variable. Never expose this key in browser code.

export RETAINDB_API_KEY="rdb_..."
export OPENAI_API_KEY="sk_..."

Create a memory client

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

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

Store a user preference

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

await user.remember("User prefers concise technical answers with short examples.");

RetainDB writes memory asynchronously where supported, so your app can keep responding quickly.

Retrieve context

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

context is a formatted string ready to place in a system message.

Call your model with memory

const response = await openai.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [
    {
      role: "system",
      content: `Use this user memory when relevant:\n${context}`
    },
    {
      role: "user",
      content: "Explain how I should call the RetainDB API."
    }
  ]
});

console.log(response.choices[0]?.message?.content);

Store what happened

After the turn, store useful new information from the user message or conversation.

await user.remember([
  { role: "user", content: "I am integrating this in a Next.js API route." },
  { role: "assistant", content: response.choices[0]?.message?.content ?? "" }
]);

Optional: one-call turn helper

The SDK also includes runTurn for non-streaming flows. It retrieves context, calls your generator, and stores the last user message.

const turn = await user.runTurn({
  messages: [{ role: "user", content: "How should I wire this into Next.js?" }],
  generate: ({ messages }) =>
    openai.chat.completions.create({
      model: "gpt-4o-mini",
      messages
    })
});

console.log(turn.response);

For streaming responses, use the manual retrieve, generate, remember pattern above.

Verify it worked

• getContext() should return the preference you stored when the query is related.
• Use the same stable userId for all requests belonging to one user.
• Keep project stable across environments.
• If a fresh memory is not visible, wait a moment and retry with the same identifiers.

Production checklist

Before wiring this into a live route:

• authenticate the user in your app before choosing userId
• keep RETAINDB_API_KEY server-side
• log trace_id from RetainDB errors
• store only useful user-provided information after each turn
• avoid sending entire transcripts back to the model when a small memory context is enough

Next: SDK quickstart, User and session memory, or Agent task API.