@octamem/octamem-js

Official SDK for OctaMem – Memory API client for the OctaMem platform.

Use it from Node.js, browsers, Deno, or Bun. TypeScript types included.

Installation

npm install @octamem/octamem-js

yarn add @octamem/octamem-js

pnpm add @octamem/octamem-js

Quick Start

import { OctaMem } from '@octamem/octamem-js';

const memory = new OctaMem('your-api-key');

// Validate key and get memory/plan/storage/wallet
const info = await memory.details();

// Search memory (uses tokens)
const results = await memory.search({
  query: 'What did we decide about the project deadline?',
  previousContext: 'We were discussing Q1 deliverables.',
});

// Store content (uses tokens and storage)
await memory.add({
  content: 'Project deadline is March 31. Frontend by March 20.',
  previousContext: 'Meeting notes from Monday.',
});

API

Base URL: https://platform.octamem.com. All endpoints use API key via Authorization: Bearer <api_key> or X-API-Key: <api_key>.

details() – Validate key and get info

Check key validity and current limits before calling search or add.

const info = await memory.details();

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

search(params) – Query memory

Sends a search query and optional previous context. Charges tokens; returns retrieval result plus tokens, cost, wallet_balance.

const data = await memory.search({
  query: 'search term',
  previousContext: 'optional prior context',
});
console.log(data.tokens, data.cost, data.wallet_balance);

add(params) – Store content

Stores content and optional context. Charges tokens and updates storage.

const data = await memory.add({
  content: 'Content to store',
  previousContext: 'optional context',
});
console.log(data.stored, data.bytes, data.tokens, data.cost);

Configuration

const memory = new OctaMem('your-api-key', {
  baseUrl: 'https://platform.octamem.com', // default
  timeout: 30_000,
  retries: 3,
  retryDelay: 1_000,
});

Error handling

import {
  OctaMem,
  AuthenticationError,
  InsufficientBalanceError,
  StorageFullError,
  AgentError,
  RateLimitError,
  NetworkError,
  TimeoutError,
  ValidationError,
} from '@octamem/octamem-js';

try {
  const memory = new OctaMem('your-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 token cost
  } else if (error instanceof StorageFullError) {
    // 400 – adding would exceed storage limit
  } else if (error instanceof AgentError) {
    // 502 – retrieval/storage agent error
  } else if (error instanceof RateLimitError) {
    // 429 – too many requests
  } else if (error instanceof NetworkError) {
    // Connection / transport failure
  } else if (error instanceof TimeoutError) {
    // Request exceeded configured timeout
  } else if (error instanceof ValidationError) {
    // Invalid input (e.g. API key format)
  }
}

TypeScript

import {
  OctaMem,
  type OctaMemConfig,
  type SearchParams,
  type SearchData,
  type AddParams,
  type AddData,
  type DetailsData,
  type DetailsDataValid,
} from '@octamem/octamem-js';

const memory = new OctaMem('your-api-key', { timeout: 60_000 });

const info: DetailsData = await memory.details();
const searchParams: SearchParams = { query: 'test', previousContext: '' };
const searchResult: SearchData = await memory.search(searchParams);
const addResult: AddData = await memory.add({ content: 'new memory' });

Browser

ES modules

<script type="module">
  import { OctaMem } from '@octamem/octamem-js';
  const memory = new OctaMem('your-api-key');
  const results = await memory.search({ query: 'test' });
  console.log(results);
</script>

UMD

<script src="https://unpkg.com/@octamem/octamem-js/dist/umd/octamem.min.js"></script>
<script>
  const memory = new OctaMem.OctaMem('your-api-key');
  memory.search({ query: 'test' }).then(console.log).catch(console.error);
</script>

CommonJS

const { OctaMem } = require('@octamem/octamem-js');
const memory = new OctaMem('your-api-key');

async function main() {
  const results = await memory.search({ query: 'test' });
  console.log(results);
}
main();

Requirements

• Node.js 16+ (18+ recommended for native fetch)
• Environments with fetch support

License

MIT