§ Interfaces

The JavaScript SDK. TypeScript-first, edge-ready.

The official JavaScript / TypeScript client for OctaMem. Works in Node.js, Bun, Deno, and any modern Edge runtime. Strict types out of the box.

Base URL: platform.octamem.com
Auth: Bearer API key
Primitives: details / search / add

Install

install

Shell

npm install octamem
# or
yarn add octamem
# or
pnpm add octamem

Requires Node.js 16 or newer, and also runs in browsers, Deno, and Bun. TypeScript definitions ship with the package, which is published on npm as npmjs.com/package/octamem.

Construct a client

client.ts

TypeScript

import { OctaMem } from "octamem";

const memory = new OctaMem(process.env.OCTAMEM_API_KEY!);

// Optional configuration.
const configured = new OctaMem(process.env.OCTAMEM_API_KEY!, {
  baseUrl: "https://platform.octamem.com",
  timeout: 30_000,
  retries: 3,
  retryDelay: 1_000,
});

The API key is the first argument. The optional second argument overrides baseUrl, timeout, retries, and retryDelay.

details()

Validate the API key and read the current plan, memory usage, storage, and wallet balance. Call it before search() or add() to confirm the key is live.

details.ts

TypeScript

const info = await memory.details();

if (info.valid) {
  console.log(info.memory, info.plan, info.wallet_balance);
} else {
  console.log(info.message);
}

search()

Query memory in natural language. Consumes tokens and returns the retrieval result plus tokens, cost, and wallet_balance.

search.ts

TypeScript

const data = await memory.search({
  query: "What did we decide about the project deadline?",
  previousContext: "We were discussing Q1 deliverables.",
});

console.log(data.tokens, data.cost, data.wallet_balance);

add()

Store content as memory. Consumes tokens and counts against your storage allowance.

add.ts

TypeScript

const data = await memory.add({
  content: "Project deadline is March 31. Frontend by March 20.",
  previousContext: "Meeting notes from Monday.",
});

console.log(data.stored, data.bytes, data.tokens, data.cost);

Errors

Every failure mode is a typed error class exported from the package, mapping onto the status codes returned by the REST API.

errors.ts

TypeScript

import {
  OctaMem,
  AuthenticationError,
  InsufficientBalanceError,
  StorageFullError,
  RateLimitError,
  NetworkError,
  TimeoutError,
  ValidationError,
} from "octamem";

try {
  const memory = new OctaMem(process.env.OCTAMEM_API_KEY!);
  await memory.add({ content: "test" });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // 401 — invalid or expired API key
  } else if (error instanceof InsufficientBalanceError) {
    // 402 — wallet cannot cover the token cost
  } else if (error instanceof StorageFullError) {
    // 400 — adding would exceed the storage limit
  } else if (error instanceof RateLimitError) {
    // 429 — back off and retry
  }
}