Memory SDK

npm install @usetransactional/memory

pnpm add @usetransactional/memory

yarn add @usetransactional/memory

import { MemoryClient } from '@usetransactional/memory';
 
const client = new MemoryClient({
  apiKey: 'your-api-key',
});
 
// Add a memory
await client.add({
  content: 'User prefers dark mode and compact layouts.',
  userId: 'user-123',
  type: 'preference',
});
 
// Search memories
const results = await client.search({
  query: 'UI preferences',
  userId: 'user-123',
  strategy: 'semantic',
});
 
// Get context for an LLM prompt
const context = await client.getContext({
  userId: 'user-123',
  query: 'Help the user customize their dashboard',
  maxTokens: 2000,
  includeProfile: true,
  includeFacts: true,
  includePreferences: true,
});

import { MemoryClient } from '@usetransactional/memory';
 
const client = new MemoryClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.usetransactional.com',
  timeout: 30000,
  maxRetries: 3,
  headers: {
    'X-Custom-Header': 'value',
  },
});

const memory = await client.add({
  content: 'User mentioned they work at Acme Corp as a senior engineer.',
  userId: 'user-123',
  sessionId: 'session-abc',
  type: 'fact',
  metadata: {
    source: 'chat',
    confidence: 0.95,
  },
});
 
console.log(memory.id); // 'mem_abc123'

const results = await client.search({
  query: 'work experience and company',
  userId: 'user-123',
  types: ['fact', 'entity'],
  strategy: 'hybrid',
  threshold: 0.7,
  limit: 10,
  includeRelated: true,
});
 
for (const result of results) {
  console.log(result.content, result.score);
}

const memory = await client.get('session-abc', 'mem_abc123');
console.log(memory.content);

await client.update('session-abc', 'mem_abc123', {
  name: 'Work Info',
  properties: {
    verified: true,
    lastConfirmed: '2025-01-15',
  },
});

await client.delete('session-abc', 'mem_abc123');

const context = await client.getContext({
  userId: 'user-123',
  sessionId: 'session-abc',
  query: 'Help the user with their project settings',
  maxTokens: 2000,
  includeProfile: true,
  includeFacts: true,
  includePreferences: true,
});
 
// Use the context in an LLM system prompt
const systemPrompt = `You are a helpful assistant. Here is what you know about the user:
 
${context.text}
 
Use this context to personalize your responses.`;

const status = await client.getJobStatus('job_xyz789');
console.log(status.state); // 'pending' | 'processing' | 'completed' | 'failed'

const session = await client.sessions.create({
  userId: 'user-123',
  agentId: 'support-bot',
  ttl: 86400, // 24 hours in seconds
  config: {
    autoExtract: true,
    autoSummarize: true,
  },
});
 
console.log(session.id); // 'ses_abc123'

const session = await client.sessions.get('ses_abc123');

import { MemorySessionStatus } from '@usetransactional/memory';
 
const sessions = await client.sessions.list({
  userId: 'user-123',
  status: MemorySessionStatus.ACTIVE,
  page: 1,
  limit: 20,
});

await client.sessions.update('ses_abc123', {
  ttl: 172800, // Extend to 48 hours
});

await client.sessions.delete('ses_abc123');

const profile = await client.profiles.get('user-123');
console.log(profile.staticFacts);  // e.g., { name: 'Jane', role: 'Engineer' }
console.log(profile.dynamicFacts); // e.g., { currentProject: 'Dashboard Redesign' }

await client.profiles.upsert('user-123', {
  staticFacts: {
    name: 'Jane Doe',
    company: 'Acme Corp',
    role: 'Senior Engineer',
  },
  dynamicFacts: {
    currentProject: 'Dashboard Redesign',
    preferredLanguage: 'TypeScript',
    timezone: 'America/New_York',
  },
});

await client.profiles.delete('user-123');

const graph = await client.graph.get({
  sessionId: 'ses_abc123',
  depth: 2,
  entityTypes: ['entity', 'topic', 'relationship'],
  limit: 50,
});
 
for (const node of graph.nodes) {
  console.log(node.name, node.type, node.properties);
}
 
for (const edge of graph.edges) {
  console.log(edge.source, '->', edge.target, `[${edge.label}]`);
}

const subgraph = await client.graph.traverse({
  startEntityId: 'ent_abc123',
  depth: 3,
  direction: 'outbound',
});

const job = await client.ingest.url({
  url: 'https://example.com/docs/getting-started',
  userId: 'user-123',
  sessionId: 'ses_abc123',
  options: {
    extractEntities: true,
    generateEmbeddings: true,
  },
});
 
// Check ingestion progress
const status = await client.getJobStatus(job.jobId);

import { readFileSync } from 'fs';
 
const pdfBuffer = readFileSync('/path/to/document.pdf');
 
const job = await client.ingest.pdf({
  file: pdfBuffer,
  filename: 'document.pdf',
  userId: 'user-123',
  options: {
    extractEntities: true,
    generateEmbeddings: true,
  },
});

const job = await client.ingest.text({
  content: '# Project Notes\n\nThe dashboard redesign uses React 19...',
  contentType: 'markdown',
  sessionId: 'ses_abc123',
});

import {
  MemoryEntityType,
  MemorySessionStatus,
  MemoryMessageRole,
} from '@usetransactional/memory';

import {
  MemoryError,
  AuthenticationError,
  ValidationError,
  NotFoundError,
  RateLimitError,
} from '@usetransactional/memory';
 
try {
  const results = await client.search({
    query: 'user preferences',
    userId: 'user-123',
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key. Check your credentials.');
  } else if (error instanceof ValidationError) {
    console.error('Invalid request parameters:', error.message);
  } else if (error instanceof NotFoundError) {
    console.error('Resource not found:', error.message);
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter} seconds.`);
  } else if (error instanceof MemoryError) {
    console.error('Memory API error:', error.message);
  }
}

import type {
  Memory,
  Session,
  SearchResult,
  ContextResult,
  MemoryEntityType,
} from '@usetransactional/memory';