Skip to main content

memory-sdk-js

Node.js / TypeScript Client SDK​

PropertyValue
Repositorymemory-sdk-js
LanguageTypeScript
TargetNode.js 18+
Package@memory-platform/sdk

Purpose​

Provides a developer-friendly, strongly-typed interface for interacting with the Memory Platform. It wraps the Memory Engine API and provides helper utilities for common agentic workflows, such as "Add Fact", "Search Context", and "Get User Profile".

This SDK is primarily used by:

  • The MCP Server (memory-mcp-server)
  • Other JavaScript-based agents or services.

Repository Structure​

memory-sdk-js/
├── package.json
├── tsconfig.json
├── README.md
├── src/
│   ├── index.ts                # Main export
│   │
│   ├── client.ts               # Core HTTP Client
│   ├── config.ts               # Configuration
│   │
│   ├── types/
│   │   ├── domain.ts           # MemoryBlock, Subject, etc.
│   │   ├── api.ts              # Request/Response aliases
│   │   └── enums.ts            # MemoryKind, etc.
│   │
│   ├── resources/
│   │   ├── memories.ts         # Memory CRUD operations
│   │   ├── packs.ts            # Pack operations
│   │   └── graph.ts            # Graph operations
│   │
│   └── utils/
│       └── error-handling.ts
│
├── tests/
│   ├── integration/
│   └── unit/

Dependencies​

{
  "name": "@memory-platform/sdk",
  "dependencies": {
    "axios": "^1.6.0",
    "zod": "^3.22.0" 
  },
  "devDependencies": {
    "typescript": "^5.3.0",
    "vitest": "^1.0.0"
  }
}

Core API Design​

Initialization​

import { MemoryClient } from '@memory-platform/sdk';

const client = new MemoryClient({
  baseUrl: 'http://localhost:8000',
  apiKey: process.env.MEMORY_API_KEY,
  defaultTenantId: 'tenant-123' 
});

1. Memory Operations​

// Create a new memory
const memory = await client.memories.create({
  subject: { type: 'user', id: 'user_123' },
  kind: 'fact',
  text: 'User is fluent in Spanish and prefers strict type checking.',
  tags: ['languages', 'coding-style'],
  confidence: 0.9
});

// Semantic Search
const results = await client.memories.search({
  query: 'coding preferences',
  subject: { type: 'user', id: 'user_123' },
  limit: 5
});

2. High-Level Helpers​

// Get a comprehensive profile
const profile = await client.packs.getProfile('user_123');
// Returns a MemoryPack[] containing basic identity, preferences, etc.

// Working Set (Context Window)
const context = await client.memories.getWorkingSet({
    subject: { type: 'project', id: 'proj_marketing_q1' },
    maxBlocks: 20
});

3. Graph Traversal​

const neighbors = await client.graph.getNeighbors({
    vertexId: 'user_123',
    maxDepth: 2,
    edgeTypes: ['WORKS_ON', 'PREFERS']
});

Implementation Guidelines​

  1. Axios Wrapper: Use an internal Axios instance with interceptors to inject X-Tenant-ID if a default tenant is configured, or ensure it's passed in method arguments.
  2. Type Safety: Mirror the Pydantic models from memory-domain as TypeScript interfaces or Zod schemas in src/types/domain.ts.
  3. Error Handling: Convert HTTP 4xx/5xx errors into typed MemoryError exceptions (e.g., MemoryNotFoundError, TenantMissingError).

Type System (Sync with memory-domain)​

The SDK MUST stay in sync with memory-domain. When the Python domain models change, these TS interfaces must be updated.

export enum MemoryKind {
  FACT = 'fact',
  PREFERENCE = 'preference',
  INSIGHT = 'insight',
  // ...
}

export interface MemoryBlock {
  id: string;
  tenant_id: string;
  kind: MemoryKind;
  content: {
    text: string;
    structured?: Record<string, any>;
  };
  scores: {
    salience: number;
    stability: number;
    confidence: number;
  };
  // ...
}