Super Agent Stack
DocsHome
New

User-level Memory

Memory that persists across all sessions for a user. Build AI that truly knows your users over time.

Overview

User-level memory stores important facts about users that persist across all their sessions. This enables your AI to remember user preferences, past interactions, and personal details even when they start a new conversation.

Basic Usage

user-memory.ts
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://www.superagentstack.com/api/v1',
  apiKey: process.env.OPENROUTER_KEY,
  defaultHeaders: { 'superAgentKey': process.env.SUPER_AGENT_KEY },
});

// Enable user-level memory
const response = await client.chat.completions.create({
  model: 'openai/gpt-4o-mini',
  messages: [{ role: 'user', content: 'What do you remember about me?' }],
  sessionId: crypto.randomUUID(),
  useUserMemory: true,      // Include user memory in context
  userMemoryTokens: 500,    // Max tokens for user memory
});

// AI will include relevant facts from previous sessions

Parameters

ParameterTypeDefaultDescription
useUserMemorybooleanfalseInclude user-level memory facts in the context.
userMemoryTokensnumber500Maximum tokens to allocate for user memory context.

Automatic Fact Extraction

User memory facts are automatically extracted from conversations when important information is detected (preferences, personal details, etc.). You can also add facts manually via the Memory API.

How It Works

  1. When useUserMemory: true, the system searches for relevant user facts
  2. Facts are ranked by relevance to the current query
  3. Top facts are included in the context (up to userMemoryTokens)
  4. The AI uses these facts to provide personalized responses

Complete Example

personalized-assistant.ts
// Session 1: User shares preferences
await client.chat.completions.create({
  model: 'openai/gpt-4o-mini',
  messages: [{ role: 'user', content: 'I prefer dark mode and use VS Code.' }],
  sessionId: 'session-1',
  saveToMemory: true,
  autoMemory: true,  // Auto-detect and save important facts
});

// Session 2 (days later): AI remembers
const response = await client.chat.completions.create({
  model: 'openai/gpt-4o-mini',
  messages: [{ role: 'user', content: 'Help me set up my development environment' }],
  sessionId: 'session-2',  // Different session!
  useUserMemory: true,     // Include user memory
});

// AI: "Since you prefer VS Code and dark mode, here's how to set up..."

Managing User Memory

You can manage user memory facts programmatically using the Memory API:

manage-memory.ts
// List user's memory facts
const facts = await fetch('/api/memory/facts?limit=10', {
  headers: { 'superAgentKey': process.env.SUPER_AGENT_KEY }
});

// Add a fact manually
await fetch('/api/memory/facts', {
  method: 'POST',
  headers: { 
    'Content-Type': 'application/json',
    'superAgentKey': process.env.SUPER_AGENT_KEY 
  },
  body: JSON.stringify({
    content: 'User prefers TypeScript over JavaScript',
    category: 'preference',
    level: 'user'
  })
});

// Delete a fact
await fetch('/api/memory/facts/fact-id', {
  method: 'DELETE',
  headers: { 'superAgentKey': process.env.SUPER_AGENT_KEY }
});