5 Minute Quickstart

This quickstart is for the developer who wants one manual proof of value. By the end, you will have created a project, written one memory, and searched for it successfully.

Before you start

You need:

• a RetainDB account
• an API key
• a terminal with curl

If you still need credentials, use sign up, project, and API key.

Step 1: create or choose a project

Create a project if you do not already have one:

curl -X POST "https://api.retaindb.com/v1/projects" \
  -H "Authorization: Bearer $RETAINDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "retaindb-quickstart"
  }'

Then set it as your default so you never need to pass it explicitly:

export RETAINDB_PROJECT="retaindb-quickstart"

Step 2: write one memory

Use the canonical memory write route:

curl -X POST "https://api.retaindb.com/v1/memory" \
  -H "Authorization: Bearer $RETAINDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "retaindb-quickstart",
    "user_id": "demo-alex",
    "session_id": "session-001",
    "content": "Alex prefers concise, direct answers.",
    "memory_type": "preference",
    "write_mode": "async"
  }'

What you should expect:

• the request is accepted quickly
• the write may continue asynchronously
• the memory may still be searchable immediately if you use include_pending: true

Step 3: search that memory

curl -X POST "https://api.retaindb.com/v1/memory/search" \
  -H "Authorization: Bearer $RETAINDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "retaindb-quickstart",
    "user_id": "demo-alex",
    "session_id": "session-001",
    "query": "How should I answer this user?",
    "include_pending": true,
    "profile": "fast",
    "top_k": 3
  }'

A successful response should include:

• at least one result containing the preference you wrote
• trace_id
• latency_breakdown

Step 4: verify that the result makes sense

Before you move on, verify these basics:

• you used the same user_id and session_id in both requests
• project matches on both sides (or RETAINDB_PROJECT is set consistently)
• you kept include_pending: true on the first search
• the result content matches what you wrote

Step 5: move to the SDK

Once the HTTP flow works, use the SDK for better defaults and less repetitive code:

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

// Reads RETAINDB_KEY from env
const db = new RetainDB({ apiKey: process.env.RETAINDB_KEY });
const openai = new OpenAI();

// Full turn — retrieve context, generate, store automatically
const { response } = await db.user("demo-alex").runTurn({
  messages: [{ role: "user", content: "How should I format my responses?" }],
  generate: (ctx) =>
    openai.chat.completions.create({
      model: "gpt-4o",
      messages: ctx.messages,
    }),
});

If something fails

401 or 403

Check that the key is valid and that you are making the request from a server-side context.

200 response but empty results

Verify user_id, session_id, and include_pending. If project is wrong the results will also be empty — check RETAINDB_PROJECT is set correctly.

You want the shortest path instead

Use Setup Wizard.

Next step

Go to SDK quickstart if you want to keep building, or memory search if you want the full request and response reference.