Guide

@rumbor/memory-sdk is the Node.js/TypeScript client for the Rumbor Memory HTTP API. It is a thin, provider-neutral wrapper: it talks only to the versioned Rumbor Memory HTTP contract and does not import Honcho, SurrealDB, SurrealQL, PostgreSQL, or Redis.

Install

npm install @rumbor/memory-sdk
Copy

Authentication

Rumbor Memory servers authenticate requests with a single Bearer credential. The server maps each configured API key to a principal UUID via its RUMBOR_AUTH_KEYS configuration (a JSON object of {"<key>": "<principal-uuid>"} pairs) - see the server's API key authentication reference for the full authorization model, including how context membership works.

From the client side, pass the key as apiKey when constructing a client:

const memory = new RumborMemory({
  baseUrl: 'https://memory.example.com',
  apiKey: process.env.RUMBOR_API_KEY,
});
Copy

The SDK sends it as Authorization: Bearer <apiKey> on every request. A missing, malformed, unknown, or duplicated credential returns a 401 response, which the SDK surfaces as a RumborMemoryError.

Quickstart

import { RumborMemory } from '@rumbor/memory-sdk';

const memory = new RumborMemory({
  baseUrl: 'http://localhost:8080',
  apiKey: process.env.RUMBOR_API_KEY,
});

const result = await memory.recall({
  context: 'acme-prod',
  query: 'When does the team deploy?',
});
Copy

context is a caller-chosen identifier scoping data (e.g. a workspace, tenant, or session group). The first successful write to a context establishes the calling principal's membership in it automatically; see the authentication reference for the full rule, including how additional principals are granted access.

Error handling

Every method rejects with a RumborMemoryError when the server responds with a non-2xx status. It carries the HTTP status and the parsed response body:

import { RumborMemory, RumborMemoryError } from '@rumbor/memory-sdk';

try {
  await memory.recall({ context: 'acme-prod', query: 'anything' });
} catch (err) {
  if (err instanceof RumborMemoryError) {
    console.error(err.status, err.body);
  }
}
Copy

Custom fetch

Pass a fetch implementation (e.g. for testing, proxying, or a non-standard runtime) via the fetch option:

const memory = new RumborMemory({
  baseUrl: 'http://localhost:8080',
  apiKey: 'test-key',
  fetch: myCustomFetch,
});
Copy

API reference

See the sidebar for the full generated reference, including every method on RumborMemory, the RumborMemoryError shape, and every input/output type.