Node SDK

npm install oramemory

Requires Node 18+ (uses global fetch). TypeScript types ship with the package — no @types/… needed.

Initialization

import { Memory } from "oramemory";

// Reads ORAMEMORY_API_KEY from env
const m = new Memory();

// Or pass explicitly
const m = new Memory({ apiKey: "om_live_...", agentId: "myai" });

// Self-hosted / staging
const m = new Memory({ apiKey: "...", baseUrl: "https://memory.mycompany.internal/api" });

Environment variables

Methods

await m.add(content, { agentId, userId, sessionId,
                       tags, category, importance, layer,
                       metadata, expireAt, inferred });

await m.read(query,   { agentId, userId, scope: "agent",
                        topK: 5, threshold: 0, category, layer });

await m.list({ agentId, userId, layer, page, pageSize });
await m.get(idMemory);
await m.update(idMemory, { content, tags, importance, ... });
await m.delete(idMemory);
await m.history(idMemory);

await m.usage();
await m.status();

Helpers

const support = m.forAgent("support");   // shallow copy
const alice   = m.forUser("alice");

await support.add("User prefers curt responses");

Error handling

All exceptions extend OraMemoryError and carry .code (HTTP status) and .body.

import { Memory, AuthError, RateLimitError, NotFoundError } from "oramemory";

try {
  await m.read("…", { agentId: "myai" });
} catch (e) {
  if (e instanceof AuthError)       { /* 401 */ }
  else if (e instanceof RateLimitError) { /* 429 — writes only */ }
  else if (e instanceof NotFoundError)  { /* 404 */ }
  else throw e;
}

Express middleware

import express from "express";
import { Memory } from "oramemory";

const app = express();
const m = new Memory({ apiKey: "om_live_..." });

app.use((req, _res, next) => {
  req.memory = m.forUser(req.headers["x-user-id"] ?? "anon");
  next();
});

app.post("/remember", async (req, res) => {
  const out = await req.memory.add(req.body.text, { agentId: "assistant" });
  res.json(out);
});