JavaScript/TypeScriptAvailable

JavaScript/TypeScript SDK

Official JavaScript and TypeScript SDK with full type definitions, async/await support, and comprehensive error handling.

Installation

# Install using npm
npm install @memory-scope/sdk

# Or with yarn
yarn add @memory-scope/sdk

# Or with pnpm
pnpm add @memory-scope/sdk

Requirements

Node.js 18 or higher
npm 7 or higher (or yarn/pnpm equivalent)

Quick Start

import { MemoryScopeClient } from '@memory-scope/sdk';

// Initialize the client
const client = new MemoryScopeClient({
  apiKey: 'your-api-key'
});

// Store a memory
const memory = await client.createMemory({
  user_id: 'user123',
  scope: 'preferences',
  domain: 'food',
  source: 'explicit_user_input',
  value_json: {
    likes: ['pizza', 'sushi'],
    dislikes: ['broccoli']
  }
});

// Read memories
const result = await client.readMemory({
  user_id: 'user123',
  scope: 'preferences',
  domain: 'food',
  purpose: 'generate food recommendations'
});

console.log(result.summary_struct);
// { likes: ['pizza', 'sushi'], dislikes: ['broccoli'] }

// Revoke access
await client.revokeMemory({
  revocation_token: result.revocation_token
});

Authentication

The SDK supports multiple ways to provide your API key:

Authentication Methods

import { MemoryScopeClient } from '@memory-scope/sdk';

// Method 1: Direct initialization
const client = new MemoryScopeClient({
  apiKey: 'sk_test_...'
});

// Method 2: Environment variable (recommended)
const client = new MemoryScopeClient({
  apiKey: process.env.MEMORY_SCOPE_API_KEY
});

// Method 3: The SDK will automatically check MEMORY_SCOPE_API_KEY env var
const client = new MemoryScopeClient();  // Uses MEMORY_SCOPE_API_KEY from environment

API Methods

createMemory()

Create a new memory with a scope, domain, and value.

createMemory

const memory = await client.createMemory({
  user_id: 'user123',
  scope: 'preferences',
  domain: 'food',
  source: 'explicit_user_input',
  ttl_days: 30,  // Optional
  value_json: {
    likes: ['pizza', 'sushi'],
    dislikes: ['broccoli']
  }
});

// Returns: MemoryCreateResponse
console.log(memory.id);
console.log(memory.expires_at);

readMemory()

Read memories with policy enforcement. Returns merged results and a revocation token.

readMemory

const result = await client.readMemory({
  user_id: 'user123',
  scope: 'preferences',
  domain: 'food',
  purpose: 'generate food recommendations',
  max_age_days: 30  // Optional
});

// Returns: MemoryReadResponse
console.log(result.summary_text);
console.log(result.summary_struct);
console.log(result.confidence);
console.log(result.revocation_token);

readMemoryContinue()

Continue reading memories using an existing revocation token.

readMemoryContinue

const result = await client.readMemoryContinue({
  revocation_token: 'rev_xyz789...'
});

// Returns: MemoryReadResponse (same format as readMemory)

revokeMemory()

Revoke access to memories using a revocation token.

revokeMemory

const response = await client.revokeMemory({
  revocation_token: 'rev_xyz789...'
});

// Returns: MemoryRevokeResponse
console.log(response.revoked);
console.log(response.revoked_at);

Error Handling

The SDK provides typed exceptions for different error types:

Error Handling

import {
  MemoryScopeClient,
  PolicyDeniedError,
  InvalidRequestError,
  AuthenticationError,
  NotFoundError,
  RateLimitError
} from '@memory-scope/sdk';

try {
  const result = await client.readMemory(...);
} catch (error) {
  if (error instanceof PolicyDeniedError) {
    console.log('Policy denied:', error.message);
  } else if (error instanceof RateLimitError) {
    console.log('Rate limit:', error.message);
    // Implement retry logic
  } else if (error instanceof AuthenticationError) {
    console.log('Auth error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

TypeScript Support

The SDK includes full TypeScript type definitions:

TypeScript Types

import { MemoryScopeClient } from '@memory-scope/sdk';
import type {
  MemoryCreateRequest,
  MemoryCreateResponse,
  MemoryReadRequest,
  MemoryReadResponse,
  MemoryRevokeRequest,
  MemoryRevokeResponse
} from '@memory-scope/sdk';

const client = new MemoryScopeClient({
  apiKey: process.env.MEMORY_SCOPE_API_KEY!
});

// Full type safety
const memory: MemoryCreateResponse = await client.createMemory({
  user_id: 'user123',
  scope: 'preferences',
  domain: 'food',
  source: 'explicit_user_input',
  value_json: { likes: ['pizza'] }
});

const result: MemoryReadResponse = await client.readMemory({
  user_id: 'user123',
  scope: 'preferences',
  domain: 'food',
  purpose: 'generate recommendations'
});

Configuration

Configure the client with custom settings:

Configuration

import { MemoryScopeClient } from '@memory-scope/sdk';

const client = new MemoryScopeClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.memoryscope.dev',  // Optional, defaults to production
  timeout: 30000,  // Request timeout in milliseconds
  maxRetries: 3  // Number of retries for failed requests
});

Browser Usage

Important Security Note

Never expose your API key in client-side code. The SDK is designed for server-side use. For browser applications, make API calls through your backend server.

The SDK works in Node.js environments. For browser usage, create API routes in your backend that use the SDK, and call those routes from your frontend.