Memory Router v1

Memory Router v1 wraps OpenAI-compatible chat calls and injects relevant RetainDB memory before the request reaches your model.

Use it when you want memory without rewriting every model call.

Install

npm install @retaindb/sdk@5

Create a router

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

const router = createMemoryRouter({
  apiKey: process.env.RETAINDB_API_KEY,
  project: "production",
  providerBaseUrl: "https://api.openai.com/v1",
  providerApiKey: process.env.OPENAI_API_KEY
});

createMemoryRouter returns a RetainDBMemoryRouter.

Route a chat request

const result = await router.chatCompletions({
  model: "gpt-4o-mini",
  messages: [
    { role: "user", content: "How should I answer this customer?" }
  ],
  userId: "user_123",
  sessionId: "support_456"
});

console.log(result.response);

Header

Memory Router v1 sends:

x-retaindb-memory-router: v1

Fallback behavior

If memory retrieval fails, the router can continue with the original provider request when best-effort fallback is enabled. Your model call keeps working, and the router result includes trace information for debugging.

Use this for chat paths where availability matters more than strict memory injection.

Observability

Log the router trace for failed or fallback requests:

if (result.fallback) {
  console.warn("RetainDB memory fallback", result.trace);
}

This makes it clear whether a model response missed memory because retrieval failed, because no memory matched, or because the provider request failed.

When not to use it

Use direct SDK calls instead when you need:

• custom retrieval ranking
• streaming-specific memory timing
• explicit storage control
• non-chat model providers

Next: SDK quickstart or OpenAI-compatible integration.