npm package: @octamem/octamem-js
Description: Official OctaMem SDK - Access your OctaMem memories from any JavaScript environment
Author: OctaMem
Latest version: 1.0.0

# @octamem/octamem-js

Official SDK for [OctaMem](https://platform.octamem.com) – Memory API client for the OctaMem platform.

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

## Installation

```bash
npm install @octamem/octamem-js
```

```bash
yarn add @octamem/octamem-js
```

```bash
pnpm add @octamem/octamem-js
```

## Quick Start

```typescript
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.

```typescript
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`.

```typescript
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.

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

## Configuration

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

## Error handling

```typescript
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

```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

```html
<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

```html
<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

```javascript
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