Queue and Diagnostics

The SDK queues writes and drains them automatically. Most apps never need to think about this.

Queue auto-drains

When you use RetainDB, the write queue drains automatically when your process exits normally (beforeExit). No manual flush needed for long-running servers.

For short-lived scripts (CLI tools, one-off jobs), flush explicitly before exiting:

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

const db = new RetainDB({ apiKey: process.env.RETAINDB_KEY });

await db.user(userId).remember("Some fact");

// Flush before the script ends
await db.queue.flush();

Check pending items:

const { queued } = db.queue.status();

Search results are cached

Identical search queries return cached results within a short window. This is intentional — it makes repeated lookups fast without extra API calls.

If you need an immediate fresh result right after a write, use include_pending: true in getContext:

const { context } = await db.user(userId).getContext("query");
// getContext always uses include_pending: true internally

Diagnostics for debugging

When something looks wrong, pull recent operations:

const recent = db.diagnostics.getLast(10);
recent.forEach(d => {
  console.log(d.operation, d.status, d.durationMs);
});

Subscribe to catch errors in real time:

db.diagnostics.subscribe((entry) => {
  if (!entry.success) {
    console.error(entry.operation, entry.errorCode, entry.errorMessage);
  }
});

Next step

• SDK Quickstart
• Memory Module Guide
• Error Taxonomy