{/* Header */}

Chat with Memory

I'll remember what you tell me across conversations

{/* Messages */}

{messages.length === 0 && (

Start a conversation!

Try saying:

"My name is Alex and I'm a software engineer"
"I prefer TypeScript over JavaScript"
"I love hiking and photography"
"What do you know about me?"

)} {messages.map((message) => (

{message.role === 'user' ? 'You' : 'Assistant'}

{message.content}

{/* Show when memories are saved */} {message.toolInvocations?.map((tool, i) => (

{tool.toolName === 'add_item' && ( <> 💾 Saved to memory )}

))}

))} {isLoading && (

)}

{/* Input */}

); } ``` ## Example Conversations ### Conversation 1: Building Context **User:** "Hi! My name is Alex and I'm a software engineer at Acme Corp." **Assistant:** "Nice to meet you, Alex! It's great to connect with a software engineer. What kind of projects do you work on at Acme Corp?" *Behind the scenes: Saves "User's name is Alex and works as a software engineer at Acme Corp"* **User:** "I really prefer TypeScript over JavaScript. The type safety is just so much better." **Assistant:** "I completely understand! TypeScript's type safety does make a huge difference in catching bugs early and improving code maintainability. Do you use TypeScript for all your projects?" *Behind the scenes: Saves "User prefers TypeScript over JavaScript for type safety"* **User:** "In my free time, I love hiking and photography. I try to get out into nature every weekend." **Assistant:** "That's a wonderful combination! Photography and hiking complement each other perfectly. Do you have a favorite hiking spot where you like to take photos?" *Behind the scenes: Saves "User enjoys hiking and photography, tries to go every weekend"* ### Conversation 2: Recalling Context (New Session) **User:** "Hey, what's up?" **Assistant:** "Hey Alex! How's it going? Did you get a chance to go hiking this weekend?" *Behind the scenes: Retrieved memories about name and hiking hobby* **User:** "I'm looking for a new side project to work on." **Assistant:** "Since you love TypeScript and photography, have you thought about building a photo management app? You could use TypeScript with Next.js for the frontend and maybe add some AI features for automatic tagging. It would combine your technical preferences with your hobby!" *Behind the scenes: Retrieved memories about TypeScript preference and photography hobby* **User:** "What do you remember about me?" **Assistant:** "Let me see... I know that your name is Alex and you work as a software engineer at Acme Corp. You prefer TypeScript over JavaScript because of the type safety. In your free time, you enjoy hiking and photography, and you try to get out into nature every weekend. Is there anything else you'd like me to remember?" *Behind the scenes: Retrieved all relevant memories* ### Conversation 3: Updating Information **User:** "Actually, I just started a new job at TechCo!" **Assistant:** "Congratulations on the new position at TechCo! That's exciting. What will you be working on there?" *Behind the scenes: Saves "User now works at TechCo" (new memory)* **User:** "Can you forget that I work at TechCo? I'd rather not share work details." **Assistant:** "Of course, I've removed that information. Your privacy is important." *Behind the scenes: Searches for and deletes work-related memories* ## Key Features Demonstrated The LLM automatically identifies and saves important information without explicit commands Context is retrieved based on meaning, not just keywords Memory operations happen transparently without disrupting conversation Users can ask what's remembered and request deletions ## Customization Ideas ```typescript theme={null} const tools = { add_preference: tool({ description: 'Save a user preference', parameters: z.object({ preference: z.string() }), execute: async ({ preference }) => { await client.addMemory(preference, { metadata: { category: 'preference' }, }); }, }), add_fact: tool({ description: 'Save a factual piece of information', parameters: z.object({ fact: z.string() }), execute: async ({ fact }) => { await client.addMemory(fact, { metadata: { category: 'fact' }, }); }, }), }; ``` ```typescript theme={null} system: `When saving memories, consider importance: - High: Core identity, strong preferences, critical information - Medium: Casual preferences, general interests - Low: Temporary states, minor details Add importance to metadata when saving.` ``` ```typescript theme={null} // After each conversation const summary = await generateSummary(messages); await client.addMemory(summary, { metadata: { type: 'conversation_summary', date: new Date().toISOString(), }, }); ``` ## Next Steps See how to store and use preferences Build a complete app Explore all memory operations Fix common issues # User Preferences Source: https://docs.usesatori.sh/examples/user-preferences Store and retrieve user preferences with memory ## Overview This example shows how to use Satori to store and retrieve user preferences, enabling personalized experiences across your application. ## Use Case Build an AI assistant that remembers user preferences for: * UI settings (theme, language, layout) * Content preferences (topics, formats, difficulty) * Communication style (formal vs casual, verbosity) * Notification preferences ## Implementation ### Saving Preferences ```typescript app/api/preferences/route.ts theme={null} import { MemoryClient } from '@usesatori/tools'; import { auth } from '@clerk/nextjs/server'; export async function POST(req: Request) { const { userId } = await auth(); if (!userId) { return new Response('Unauthorized', { status: 401 }); } const { preference, category } = await req.json(); const client = new MemoryClient({ apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId, }); // Save preference with metadata await client.addMemory(preference, { metadata: { type: 'preference', category, timestamp: new Date().toISOString(), }, }); return Response.json({ success: true }); } ``` ### Retrieving Preferences ```typescript app/api/preferences/get/route.ts theme={null} import { MemoryClient } from '@usesatori/tools'; import { auth } from '@clerk/nextjs/server'; export async function GET(req: Request) { const { userId } = await auth(); if (!userId) { return new Response('Unauthorized', { status: 401 }); } const { searchParams } = new URL(req.url); const category = searchParams.get('category'); const client = new MemoryClient({ apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId, }); // Search for preferences in a specific category const query = category ? `${category} preferences` : 'user preferences'; const preferences = await client.searchMemories(query, { limit: 20, threshold: 0.7, }); // Filter by metadata if needed const filtered = category ? preferences.filter(p => p.metadata?.category === category) : preferences; return Response.json({ preferences: filtered }); } ``` ### Preferences UI Component ```typescript components/PreferencesPanel.tsx theme={null} 'use client'; import { useState, useEffect } from 'react'; interface Preference { id: string; content: string; category: string; createdAt: string; } export function PreferencesPanel() { const [preferences, setPreferences] = useState([]); const [newPref, setNewPref] = useState(''); const [category, setCategory] = useState('general'); useEffect(() => { loadPreferences(); }, []); async function loadPreferences() { const response = await fetch('/api/preferences/get'); const data = await response.json(); setPreferences(data.preferences); } async function savePreference() { await fetch('/api/preferences', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ preference: newPref, category, }), }); setNewPref(''); loadPreferences(); } return (

Your Preferences

{/* Add Preference */}

Add New Preference

setNewPref(e.target.value)} placeholder="e.g., I prefer dark mode" className="w-full p-2 border rounded" />

{/* Preferences List */}

Saved Preferences

{preferences.length === 0 ? (

No preferences saved yet

) : ( preferences.map((pref) => (

{pref.category}

{pref.content}

{new Date(pref.createdAt).toLocaleDateString()}

)) )}

); } ``` ## Preference Categories ### UI Preferences ```typescript theme={null} // Theme preference await client.addMemory('User prefers dark mode', { metadata: { category: 'ui', subcategory: 'theme' }, }); // Layout preference await client.addMemory('User prefers compact layout with sidebar', { metadata: { category: 'ui', subcategory: 'layout' }, }); // Language preference await client.addMemory('User prefers Spanish language', { metadata: { category: 'ui', subcategory: 'language' }, }); ``` ### Content Preferences ```typescript theme={null} // Topic interests await client.addMemory('User is interested in AI and machine learning', { metadata: { category: 'content', subcategory: 'topics' }, }); // Content format await client.addMemory('User prefers video tutorials over text articles', { metadata: { category: 'content', subcategory: 'format' }, }); // Difficulty level await client.addMemory('User prefers advanced technical content', { metadata: { category: 'content', subcategory: 'difficulty' }, }); ``` ### Communication Preferences ```typescript theme={null} // Tone preference await client.addMemory('User prefers casual, friendly communication', { metadata: { category: 'communication', subcategory: 'tone' }, }); // Verbosity await client.addMemory('User prefers concise responses', { metadata: { category: 'communication', subcategory: 'verbosity' }, }); // Explanation style await client.addMemory('User likes code examples with explanations', { metadata: { category: 'communication', subcategory: 'style' }, }); ``` ## Using Preferences in Chat ```typescript app/api/chat/route.ts theme={null} import { streamText } from 'ai'; import { openai } from '@ai-sdk/openai'; import { MemoryClient } from '@usesatori/tools'; export async function POST(req: Request) { const { userId } = await auth(); const { messages } = await req.json(); const client = new MemoryClient({ apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId: userId!, }); // Fetch user preferences const preferences = await client.searchMemories('user preferences', { limit: 10, }); // Build preferences context const preferencesContext = preferences .map(p => p.content) .join('\n'); const result = await streamText({ model: openai('gpt-4o'), system: `You are a helpful assistant. Adapt your responses based on these user preferences: ${preferencesContext} Follow these preferences in your communication style, content recommendations, and overall interaction.`, messages, }); return result.toDataStreamResponse(); } ``` ## Example Interactions **User:** "I prefer dark mode and a compact layout" **Assistant:** "Got it! I'll remember that you prefer dark mode and a compact layout. Your interface should reflect these preferences." *Saves: "User prefers dark mode" and "User prefers compact layout"* **User:** "Show me some tutorials" **Assistant:** "Based on your preferences for advanced technical content in video format, here are some great video tutorials on AI and machine learning..." *Uses preferences to personalize recommendations* **User:** "Explain how embeddings work" **Assistant:** "Sure! Here's a concise explanation with code: ```python theme={null} # Embeddings convert text to vectors embedding = model.encode('Hello world') # Result: [0.23, -0.45, 0.67, ...] ``` Embeddings capture semantic meaning in numbers that computers can compare." *Adapts to preference for concise responses with code examples* ## Advanced Patterns ### Preference Conflicts ```typescript theme={null} // Handle conflicting preferences const preferences = await client.searchMemories('theme preference'); // If multiple theme preferences exist, use the most recent const sortedByDate = preferences.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime() ); const currentTheme = sortedByDate[0]; ``` ### Preference Hierarchy ```typescript theme={null} // Define preference importance await client.addMemory('User strongly prefers TypeScript', { metadata: { category: 'content', importance: 'high', strength: 'strong', }, }); await client.addMemory('User somewhat likes Python', { metadata: { category: 'content', importance: 'medium', strength: 'moderate', }, }); ``` ### Preference Expiration ```typescript theme={null} // Add expiration to temporary preferences await client.addMemory('User is currently learning React', { metadata: { category: 'content', temporary: true, expiresAt: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString(), }, }); // Clean up expired preferences const allPrefs = await client.getAllMemories(); const now = Date.now(); for (const pref of allPrefs) { if (pref.metadata?.expiresAt) { const expiresAt = new Date(pref.metadata.expiresAt).getTime(); if (now > expiresAt) { await client.deleteMemory(pref.id); } } } ``` ## Best Practices ```typescript theme={null} // ✅ Good: Specific and actionable "User prefers dark mode with high contrast" "User wants email notifications only for critical alerts" // ❌ Bad: Vague "User likes dark stuff" "User doesn't want spam" ``` ```typescript theme={null} await client.addMemory('User prefers TypeScript', { metadata: { category: 'programming', subcategory: 'languages', importance: 'high', source: 'explicit', // vs 'inferred' confidence: 0.95, }, }); ``` ```typescript theme={null} // Search for existing preference const existing = await client.searchMemories('theme preference', { threshold: 0.9, }); // Delete old preference if (existing.length > 0) { await client.deleteMemory(existing[0].id); } // Add new preference await client.addMemory('User now prefers light mode'); ``` ## Next Steps See memory in conversations Learn the MemoryClient API Explore search options Learn about metadata # Direct Client Usage Source: https://docs.usesatori.sh/guides/direct-client Use the MemoryClient directly for custom integrations and advanced use cases ## Overview While the `memoryTools()` helper is great for Vercel AI SDK integration, you can also use the `MemoryClient` directly for more control over memory operations. This is useful for: * Custom AI frameworks * Background jobs that manage memories * Admin interfaces for viewing/managing memories * Non-LLM use cases ## Installation ```bash theme={null} npm install @usesatori/tools ``` ## Basic Usage ### Creating a Client ```typescript theme={null} import { MemoryClient } from '@usesatori/tools'; const client = new MemoryClient({ apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId: 'user-123', }); ``` ### Adding Memories ```typescript theme={null} const memory = await client.addMemory( 'User prefers TypeScript over JavaScript' ); console.log('Saved memory:', memory.id); ``` With metadata: ```typescript theme={null} const memory = await client.addMemory( 'User prefers dark mode in all applications', { metadata: { category: 'preference', tags: ['ui', 'theme'], importance: 'high', }, } ); ``` ### Searching Memories ```typescript theme={null} const memories = await client.searchMemories('programming languages'); memories.forEach((memory) => { console.log(`${memory.content} (similarity: ${memory.similarity})`); }); ``` With options: ```typescript theme={null} const memories = await client.searchMemories('preferences', { limit: 5, threshold: 0.8, // Only very similar memories }); ``` ### Getting All Memories ```typescript theme={null} const allMemories = await client.getAllMemories(); console.log(`Total memories: ${allMemories.length}`); ``` With limit: ```typescript theme={null} const recentMemories = await client.getAllMemories({ limit: 10 }); ``` ### Deleting Memories ```typescript theme={null} await client.deleteMemory('memory-uuid'); console.log('Memory deleted'); ``` ## Complete API Reference ### Constructor Your Satori API key Satori server URL (e.g., `https://api.usesatori.sh`) User identifier for memory isolation ### Methods #### addMemory(content, options?) Saves a new memory. The text content to save Optional metadata for organization ```typescript theme={null} { category: 'preference', tags: ['important'], customField: 'value' } ``` **Returns:** `Promise` ```typescript theme={null} { id: 'uuid', content: 'User prefers TypeScript', userId: 'user-123', metadata: { category: 'preference' }, createdAt: '2024-01-15T10:30:00Z', updatedAt: '2024-01-15T10:30:00Z' } ``` #### searchMemories(query, options?) Searches for semantically similar memories. Natural language search query Maximum number of results (1-100) Minimum similarity score (0-1) **Returns:** `Promise` ```typescript theme={null} [ { id: 'uuid', content: 'User prefers TypeScript', similarity: 0.92, userId: 'user-123', metadata: {}, createdAt: '2024-01-15T10:30:00Z', updatedAt: '2024-01-15T10:30:00Z' } ] ``` #### getAllMemories(options?) Retrieves all memories for the user. Maximum number of memories to return **Returns:** `Promise` #### deleteMemory(id) Deletes a specific memory. UUID of the memory to delete **Returns:** `Promise` ## Advanced Use Cases ### Building an Admin Dashboard ```typescript theme={null} import { MemoryClient } from '@usesatori/tools'; export async function GET(req: Request) { const { searchParams } = new URL(req.url); const userId = searchParams.get('userId'); if (!userId) { return new Response('Missing userId', { status: 400 }); } const client = new MemoryClient({ apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId, }); const memories = await client.getAllMemories(); return Response.json({ userId, totalMemories: memories.length, memories: memories.map((m) => ({ id: m.id, content: m.content, createdAt: m.createdAt, metadata: m.metadata, })), }); } ``` ### Background Memory Processing ```typescript theme={null} // Cron job to clean up old memories import { MemoryClient } from '@usesatori/tools'; async function cleanupOldMemories(userId: string) { const client = new MemoryClient({ apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId, }); const memories = await client.getAllMemories(); const sixMonthsAgo = Date.now() - 6 * 30 * 24 * 60 * 60 * 1000; for (const memory of memories) { const createdAt = new Date(memory.createdAt).getTime(); if (createdAt < sixMonthsAgo) { await client.deleteMemory(memory.id); console.log(`Deleted old memory: ${memory.id}`); } } } ``` ### Memory Export ```typescript theme={null} // Export user data for GDPR compliance async function exportUserMemories(userId: string) { const client = new MemoryClient({ apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId, }); const memories = await client.getAllMemories(); const exportData = { userId, exportDate: new Date().toISOString(), totalMemories: memories.length, memories: memories.map((m) => ({ content: m.content, createdAt: m.createdAt, metadata: m.metadata, })), }; return JSON.stringify(exportData, null, 2); } ``` ### Custom AI Framework Integration ```typescript theme={null} import { MemoryClient } from '@usesatori/tools'; import Anthropic from '@anthropic-ai/sdk'; const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY!, }); const memoryClient = new MemoryClient({ apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId: 'user-123', }); async function chatWithMemory(userMessage: string) { // Search for relevant context const relevantMemories = await memoryClient.searchMemories(userMessage, { limit: 5, }); const context = relevantMemories .map((m) => m.content) .join('\n'); // Call Claude with context const response = await anthropic.messages.create({ model: 'claude-3-5-sonnet-20241022', max_tokens: 1024, messages: [ { role: 'user', content: `Context about the user:\n${context}\n\nUser message: ${userMessage}`, }, ], }); // Extract and save any important information const responseText = response.content[0].text; // Simple heuristic: if user said "remember" or "I am/like/prefer" if (/remember|I am|I like|I prefer/i.test(userMessage)) { await memoryClient.addMemory(userMessage); } return responseText; } ``` ## Error Handling Handle errors appropriately: ```typescript theme={null} try { const memories = await client.searchMemories('query'); } catch (error) { if (error instanceof Error) { if (error.message.includes('Unauthorized')) { console.error('Invalid API key'); } else if (error.message.includes('rate limit')) { console.error('Rate limit exceeded'); // Implement exponential backoff } else if (error.message.includes('Not Found')) { console.error('Memory not found'); } else { console.error('Unknown error:', error.message); } } throw error; } ``` ## TypeScript Types The client exports TypeScript types for all operations: ```typescript theme={null} import type { Memory, MemoryWithSimilarity, AddMemoryOptions, SearchOptions } from '@usesatori/tools'; const memory: Memory = { id: 'uuid', content: 'User prefers TypeScript', userId: 'user-123', clerkUserId: 'user_372Icb...', metadata: {}, createdAt: '2024-01-15T10:30:00Z', updatedAt: '2024-01-15T10:30:00Z', }; const searchResult: MemoryWithSimilarity = { ...memory, similarity: 0.92, }; ``` ## Testing Mock the client for testing: ```typescript theme={null} import { MemoryClient } from '@usesatori/tools'; // Mock the client jest.mock('@usesatori/tools', () => ({ MemoryClient: jest.fn().mockImplementation(() => ({ addMemory: jest.fn().mockResolvedValue({ id: 'test-uuid', content: 'Test memory', userId: 'test-user', metadata: {}, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(), }), searchMemories: jest.fn().mockResolvedValue([]), getAllMemories: jest.fn().mockResolvedValue([]), deleteMemory: jest.fn().mockResolvedValue(undefined), })), })); describe('Memory operations', () => { it('saves a memory', async () => { const client = new MemoryClient({ apiKey: 'test-key', baseUrl: 'http://localhost:3001', userId: 'test-user', }); const memory = await client.addMemory('Test content'); expect(memory.content).toBe('Test memory'); }); }); ``` ## Best Practices Create one client per user and reuse it: ```typescript theme={null} // ✅ Good: Reuse client const client = new MemoryClient(config); await client.addMemory('Memory 1'); await client.addMemory('Memory 2'); // ❌ Bad: Create new client each time await new MemoryClient(config).addMemory('Memory 1'); await new MemoryClient(config).addMemory('Memory 2'); ``` Store complete, self-contained information: ```typescript theme={null} // ✅ Good await client.addMemory('User prefers dark mode in all applications'); // ❌ Bad await client.addMemory('dark mode'); // Too vague ``` Use metadata to categorize and filter memories: ```typescript theme={null} await client.addMemory('User prefers TypeScript', { metadata: { category: 'preference', subcategory: 'programming', tags: ['language', 'typescript'], importance: 'high', }, }); ``` Always wrap operations in try-catch blocks: ```typescript theme={null} try { await client.addMemory(content); } catch (error) { console.error('Failed to save memory:', error); // Fallback behavior } ``` ## Next Steps Learn about the AI SDK integration Explore the complete API documentation See complete implementations Fix common issues # Next.js Integration Source: https://docs.usesatori.sh/guides/nextjs-integration Build a complete Next.js application with Satori memory integration ## Overview This guide walks you through building a complete Next.js application with Satori memory, including: * Chat interface with memory * User authentication * Memory dashboard * API routes with proper error handling ## Project Setup ```bash theme={null} npx create-next-app@latest my-memory-app cd my-memory-app ``` Choose these options: * TypeScript: Yes * ESLint: Yes * Tailwind CSS: Yes * App Router: Yes ```bash theme={null} npm install @usesatori/tools ai @ai-sdk/openai @clerk/nextjs ``` ```bash .env.local theme={null} # Satori SATORI_API_KEY=sk_satori_... SATORI_URL=https://api.usesatori.sh # OpenAI OPENAI_API_KEY=sk-... # Clerk (for authentication) NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_... CLERK_SECRET_KEY=sk_... ``` ## Authentication Setup ### Configure Clerk ```typescript middleware.ts theme={null} import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'; const isPublicRoute = createRouteMatcher(['/sign-in(.*)', '/sign-up(.*)']); export default clerkMiddleware(async (auth, request) => { if (!isPublicRoute(request)) { await auth.protect(); } }); export const config = { matcher: [ '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)', '/(api|trpc)(.*)', ], }; ``` ### Root Layout ```typescript app/layout.tsx theme={null} import { ClerkProvider } from '@clerk/nextjs'; import './globals.css'; export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( {children} ); } ``` ## Chat API Route Create a memory-enabled chat endpoint: ```typescript app/api/chat/route.ts theme={null} import { streamText } from 'ai'; import { openai } from '@ai-sdk/openai'; import { memoryTools, getContext } from '@usesatori/tools'; import { auth } from '@clerk/nextjs/server'; export async function POST(req: Request) { try { // Authenticate user const { userId } = await auth(); if (!userId) { return new Response('Unauthorized', { status: 401 }); } // Parse request const { messages } = await req.json(); if (!messages || !Array.isArray(messages) || messages.length === 0) { return new Response('Invalid request', { status: 400 }); } const userMessage = messages[messages.length - 1].content; // Configure memory const memoryConfig = { apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId, }; // Create memory tools const tools = memoryTools(memoryConfig); // Pre-fetch relevant context let memoryContext = ''; try { memoryContext = await getContext( memoryConfig, userMessage, { limit: 5 } ); } catch (error) { console.error('Failed to fetch memory context:', error); // Continue without context } // Stream response with memory const result = await streamText({ model: openai('gpt-4o'), system: `You are a helpful assistant with long-term memory. ${memoryContext ? `What you know about this user:\n${memoryContext}\n` : ''} When the user shares important information, use the add_item tool to save it. Be natural and conversational. Don't explicitly mention that you're saving memories.`, messages, tools, maxSteps: 5, }); return result.toDataStreamResponse(); } catch (error) { console.error('Chat error:', error); return new Response( JSON.stringify({ error: 'Failed to process message' }), { status: 500, headers: { 'Content-Type': 'application/json' } } ); } } ``` ## Chat Page Create an interactive chat interface: ```typescript app/chat/page.tsx theme={null} 'use client'; import { useChat } from 'ai/react'; import { useUser } from '@clerk/nextjs'; import { useState } from 'react'; export default function ChatPage() { const { user, isLoaded } = useUser(); const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat(); const [showMemorySaved, setShowMemorySaved] = useState(false); if (!isLoaded) { return

; } return (

{/* Header */}

Chat with Memory

Signed in as {user?.firstName || user?.emailAddresses[0].emailAddress}

View Memories

{/* Messages */}

{messages.length === 0 && (

Start a conversation!

Try saying: "Remember that I love TypeScript"

)} {messages.map((message) => (

{message.role === 'user' ? 'You' : 'Assistant'}

{message.content}

{/* Show tool calls */} {message.toolInvocations?.map((tool, i) => (

{tool.toolName === 'add_item' && ( 💾 Saved to memory )}

))}

))} {isLoading && (

)}

{/* Input */}

); } ``` ## Memory Dashboard Create a page to view and manage memories: ```typescript app/dashboard/page.tsx theme={null} 'use client'; import { useEffect, useState } from 'react'; import { useUser } from '@clerk/nextjs'; import { MemoryClient } from '@usesatori/tools'; interface Memory { id: string; content: string; createdAt: string; metadata?: Record; } export default function DashboardPage() { const { user, isLoaded } = useUser(); const [memories, setMemories] = useState([]); const [loading, setLoading] = useState(true); const [searchQuery, setSearchQuery] = useState(''); useEffect(() => { if (isLoaded && user) { loadMemories(); } }, [isLoaded, user]); async function loadMemories() { try { const response = await fetch('/api/memories'); const data = await response.json(); setMemories(data.memories || []); } catch (error) { console.error('Failed to load memories:', error); } finally { setLoading(false); } } async function deleteMemory(id: string) { if (!confirm('Are you sure you want to delete this memory?')) { return; } try { await fetch(`/api/memories/${id}`, { method: 'DELETE' }); setMemories(memories.filter((m) => m.id !== id)); } catch (error) { console.error('Failed to delete memory:', error); } } async function searchMemories() { if (!searchQuery.trim()) { loadMemories(); return; } try { const response = await fetch( `/api/memories/search?q=${encodeURIComponent(searchQuery)}` ); const data = await response.json(); setMemories(data.memories || []); } catch (error) { console.error('Failed to search memories:', error); } } if (!isLoaded || loading) { return

; } return (

{/* Header */}

Your Memories

{memories.length} {memories.length === 1 ? 'memory' : 'memories'} stored

Back to Chat

{/* Search */}

setSearchQuery(e.target.value)} onKeyDown={(e) => e.key === 'Enter' && searchMemories()} placeholder="Search memories..." className="flex-1 p-3 border rounded-lg focus:outline-none focus:ring-2 focus:ring-purple-600" /> {searchQuery && ( )}

{/* Memories List */}

{memories.length === 0 ? (

No memories yet

Start chatting to create some memories!

) : ( memories.map((memory) => (

{memory.content}

{new Date(memory.createdAt).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric', hour: '2-digit', minute: '2-digit', })}

)) )}

); } ``` ## Memory API Routes ### Get All Memories ```typescript app/api/memories/route.ts theme={null} import { auth } from '@clerk/nextjs/server'; import { MemoryClient } from '@usesatori/tools'; export async function GET() { try { const { userId } = await auth(); if (!userId) { return new Response('Unauthorized', { status: 401 }); } const client = new MemoryClient({ apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId, }); const memories = await client.getAllMemories(); return Response.json({ memories }); } catch (error) { console.error('Failed to fetch memories:', error); return new Response('Internal Server Error', { status: 500 }); } } ``` ### Search Memories ```typescript app/api/memories/search/route.ts theme={null} import { auth } from '@clerk/nextjs/server'; import { MemoryClient } from '@usesatori/tools'; export async function GET(req: Request) { try { const { userId } = await auth(); if (!userId) { return new Response('Unauthorized', { status: 401 }); } const { searchParams } = new URL(req.url); const query = searchParams.get('q'); if (!query) { return new Response('Missing query parameter', { status: 400 }); } const client = new MemoryClient({ apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId, }); const memories = await client.searchMemories(query); return Response.json({ memories }); } catch (error) { console.error('Failed to search memories:', error); return new Response('Internal Server Error', { status: 500 }); } } ``` ### Delete Memory ```typescript app/api/memories/[id]/route.ts theme={null} import { auth } from '@clerk/nextjs/server'; import { MemoryClient } from '@usesatori/tools'; export async function DELETE( req: Request, { params }: { params: { id: string } } ) { try { const { userId } = await auth(); if (!userId) { return new Response('Unauthorized', { status: 401 }); } const client = new MemoryClient({ apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId, }); await client.deleteMemory(params.id); return Response.json({ success: true }); } catch (error) { console.error('Failed to delete memory:', error); return new Response('Internal Server Error', { status: 500 }); } } ``` ## Running the Application ```bash theme={null} npm run dev ``` Open [http://localhost:3000](http://localhost:3000) in your browser Create an account or sign in with Clerk Try these prompts: * "Remember that I love TypeScript" * "My favorite color is blue" * "What do you know about me?" Click "View Memories" to see all stored memories ## Next Steps Deploy your application to production Explore advanced examples Learn about all available endpoints Fix common issues # Vercel AI SDK Integration Source: https://docs.usesatori.sh/guides/vercel-ai-sdk Complete guide to integrating Satori memory with the Vercel AI SDK ## Overview Satori provides first-class integration with the Vercel AI SDK through the `@usesatori/tools` package. This guide covers everything from basic setup to advanced patterns. ## Installation ```bash npm theme={null} npm install @usesatori/tools ai @ai-sdk/openai ``` ```bash pnpm theme={null} pnpm add @usesatori/tools ai @ai-sdk/openai ``` ```bash yarn theme={null} yarn add @usesatori/tools ai @ai-sdk/openai ``` ## Basic Integration ### Step 1: Create Memory Tools The `memoryTools()` function creates AI SDK-compatible tools that the LLM can use to manage memories: ```typescript theme={null} import { memoryTools, getContext } from '@usesatori/tools'; const tools = memoryTools({ apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId: 'user-123', }); ``` ### Step 2: Pre-fetch Memory Context Fetch relevant memories before calling the LLM: ```typescript theme={null} const memoryContext = await getContext( { apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId: 'user-123', }, userMessage, { limit: 5, threshold: 0.7 } ); ``` ### Step 3: Stream with Memory Use `streamText()` with memory tools and context: ```typescript theme={null} import { streamText } from 'ai'; import { openai } from '@ai-sdk/openai'; const result = await streamText({ model: openai('gpt-4o'), system: `You are a helpful assistant with long-term memory. What you know about this user: ${memoryContext} When the user shares important information, use the add_item tool to save it.`, messages, tools, }); return result.toDataStreamResponse(); ``` ## Complete API Route Example Here's a full Next.js API route with memory: ```typescript app/api/chat/route.ts theme={null} import { streamText } from 'ai'; import { openai } from '@ai-sdk/openai'; import { memoryTools, getContext } from '@usesatori/tools'; export async function POST(req: Request) { try { const { messages } = await req.json(); const userMessage = messages[messages.length - 1].content; // Get user ID from your auth system const session = await getSession(req); if (!session?.userId) { return new Response('Unauthorized', { status: 401 }); } // Create memory configuration const memoryConfig = { apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId: session.userId, }; // Create memory tools const tools = memoryTools(memoryConfig); // Pre-fetch relevant context const memoryContext = await getContext( memoryConfig, userMessage, { limit: 5 } ); // Stream response with memory const result = await streamText({ model: openai('gpt-4o'), system: `You are a helpful assistant with long-term memory. What you know about this user: ${memoryContext} Use the add_item tool when the user: - Shares preferences or opinions - Provides personal information - Mentions important dates or events - Expresses goals or intentions Be natural and conversational. Don't explicitly mention that you're saving memories.`, messages, tools, maxSteps: 5, // Allow multiple tool calls }); return result.toDataStreamResponse(); } catch (error) { console.error('Chat error:', error); return new Response('Internal Server Error', { status: 500 }); } } ``` Set `maxSteps: 5` to allow the LLM to make multiple tool calls in a single response (e.g., search and then save). ## Available Tools The `memoryTools()` function provides two tools: ### add\_item Saves information to memory. The LLM calls this automatically when it detects important information. ```typescript theme={null} // LLM automatically calls this { tool: 'add_item', parameters: { memory: 'User prefers TypeScript over JavaScript for type safety' } } ``` The information to save. Should be a complete, self-contained statement. Optional metadata for categorization: ```typescript theme={null} { memory: 'User prefers TypeScript', metadata: { category: 'preferences', tags: ['programming', 'languages'] } } ``` ### delete\_memory Removes a specific memory by ID. ```typescript theme={null} // LLM calls this when user asks to forget something { tool: 'delete_memory', parameters: { memoryId: 'uuid-of-memory' } } ``` The UUID of the memory to delete. The LLM can get this from the context. ## Advanced Patterns ### Pattern 1: Conditional Context Injection Only inject context when relevant: ```typescript theme={null} const userMessage = messages[messages.length - 1].content; // Check if message might need memory context const needsContext = /what|remember|know|told|said/i.test(userMessage); let memoryContext = ''; if (needsContext) { memoryContext = await getContext(config, userMessage); } const result = await streamText({ model: openai('gpt-4o'), system: `You are a helpful assistant. ${memoryContext ? `\nWhat you know:\n${memoryContext}` : ''}`, messages, tools, }); ``` ### Pattern 2: Category-Based Memory Use metadata to organize memories by category: ```typescript theme={null} const tools = { add_preference: tool({ description: 'Save a user preference', parameters: z.object({ preference: z.string(), }), execute: async ({ preference }) => { await client.addMemory(preference, { metadata: { category: 'preference' }, }); return 'Preference saved'; }, }), add_fact: tool({ description: 'Save a factual piece of information', parameters: z.object({ fact: z.string(), }), execute: async ({ fact }) => { await client.addMemory(fact, { metadata: { category: 'fact' }, }); return 'Fact saved'; }, }), }; ``` ### Pattern 3: Streaming with Tool Call Feedback Show users when memories are being saved: ```typescript theme={null} 'use client'; import { useChat } from 'ai/react'; export default function ChatPage() { const { messages, input, handleInputChange, handleSubmit } = useChat({ onToolCall: ({ toolCall }) => { if (toolCall.toolName === 'add_item') { console.log('Saving memory:', toolCall.args.memory); // Show toast notification } }, }); return (

{messages.map((message) => (

{message.content}

{/* Show tool calls */} {message.toolInvocations?.map((tool, i) => (

{tool.toolName === 'add_item' && ( 💾 Saved to memory )}

))}

); } ``` ### Pattern 4: Multi-Step Reasoning Allow the LLM to search before responding: ```typescript theme={null} const tools = { ...memoryTools(config), search_memory: tool({ description: 'Search for relevant memories', parameters: z.object({ query: z.string().describe('What to search for'), }), execute: async ({ query }) => { const memories = await client.searchMemories(query, { limit: 3 }); return memories.map(m => m.content).join('\n'); }, }), }; const result = await streamText({ model: openai('gpt-4o'), system: `You are a helpful assistant with memory. Use search_memory to find relevant information before answering questions. Use add_item to save important new information.`, messages, tools, maxSteps: 5, // Allow search → respond → save flow }); ``` This pattern is less reliable than pre-fetching context. The LLM may not always call `search_memory` when needed. ## Error Handling Handle errors gracefully in production: ```typescript theme={null} export async function POST(req: Request) { try { const { messages } = await req.json(); // Validate input if (!messages || !Array.isArray(messages)) { return new Response('Invalid request', { status: 400 }); } const memoryConfig = { apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId: session.userId, }; // Try to fetch context, but don't fail if it errors let memoryContext = ''; try { memoryContext = await getContext( memoryConfig, messages[messages.length - 1].content ); } catch (error) { console.error('Failed to fetch memory context:', error); // Continue without context } const tools = memoryTools(memoryConfig); const result = await streamText({ model: openai('gpt-4o'), system: `You are a helpful assistant. ${memoryContext ? `\nWhat you know:\n${memoryContext}` : ''}`, messages, tools, }); return result.toDataStreamResponse(); } catch (error) { console.error('Chat error:', error); // Return user-friendly error return new Response( JSON.stringify({ error: 'Failed to process message' }), { status: 500, headers: { 'Content-Type': 'application/json' } } ); } } ``` ## Testing Test your memory integration: ```typescript theme={null} import { POST } from './route'; describe('Chat API with Memory', () => { it('saves memories when user shares information', async () => { const request = new Request('http://localhost:3000/api/chat', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ messages: [ { role: 'user', content: 'Remember that I love TypeScript' } ], }), }); const response = await POST(request); expect(response.status).toBe(200); // Verify memory was saved const memories = await client.searchMemories('TypeScript'); expect(memories).toHaveLength(1); expect(memories[0].content).toContain('TypeScript'); }); }); ``` ## Performance Optimization ```typescript theme={null} const embeddingCache = new Map(); async function getCachedContext(query: string) { if (embeddingCache.has(query)) { return embeddingCache.get(query)!; } const context = await getContext(config, query); embeddingCache.set(query, context); return context; } ``` ```typescript theme={null} // Fetch context and start LLM call in parallel const [memoryContext] = await Promise.all([ getContext(config, userMessage), // Other async operations ]); ``` ```typescript theme={null} // Fetch fewer memories for faster responses const context = await getContext(config, userMessage, { limit: 3, // Instead of default 10 }); ``` ## Next Steps Use MemoryClient for custom integrations Build a complete Next.js app with memory Explore the complete API See complete implementations # AI with Long-Term Memory Source: https://docs.usesatori.sh/index Give your AI applications persistent memory that remembers user preferences, context, and conversations across sessions ## What is Satori? Satori is a memory layer for AI applications that enables your agents to remember information across conversations. Built on semantic search with vector embeddings, Satori automatically stores and retrieves relevant context to make your AI more personalized and context-aware. Get your first memory working in under 5 minutes with the Vercel AI SDK Explore the complete tRPC API for memory operations Learn about embeddings, semantic search, and memory isolation See real-world implementations with complete code ## Key Features Find relevant memories using natural language queries powered by vector embeddings Built-in tenant isolation ensures your users' data stays completely separate Drop-in tools for Vercel AI SDK with automatic memory management End-to-end type safety with tRPC from your backend to frontend ## How It Works ```mermaid theme={null} sequenceDiagram participant User participant App participant LLM participant Satori User->>App: "Remember I like TypeScript" App->>Satori: Search relevant memories Satori-->>App: Return context App->>LLM: Message + memory context LLM->>Satori: add_item tool call Satori-->>LLM: Memory saved LLM-->>User: "Got it! I'll remember that." ``` Your application receives input from the user Satori searches for relevant memories using semantic similarity The AI model receives the message along with relevant memories The LLM uses tools to save important information for future conversations ## Installation ```bash npm theme={null} npm install @usesatori/tools ai ``` ```bash pnpm theme={null} pnpm add @usesatori/tools ai ``` ```bash yarn theme={null} yarn add @usesatori/tools ai ``` ## Quick Example ```typescript theme={null} import { streamText } from 'ai'; import { openai } from '@ai-sdk/openai'; import { memoryTools, getContext } from '@usesatori/tools'; // Create memory tools for a user const tools = memoryTools({ apiKey: process.env.SATORI_API_KEY!, baseUrl: 'https://api.usesatori.sh', userId: 'user-123', }); // Pre-fetch relevant memories const context = await getContext( { apiKey: process.env.SATORI_API_KEY!, baseUrl: 'https://api.usesatori.sh', userId: 'user-123', }, userMessage ); // Stream with memory const result = await streamText({ model: openai('gpt-4o'), system: `You are a helpful assistant with memory. What you know about this user: ${context} Use add_item to save important information.`, messages, tools, }); ``` The LLM automatically decides when to save memories using the `add_item` tool. You don't need to manually parse or store information. ## Use Cases Build assistants that remember user preferences, work context, and conversation history to provide increasingly personalized responses over time. Enable support agents to access previous interactions, known issues, and customer preferences without asking repetitive questions. Create tutors that track student progress, learning style preferences, and areas of difficulty to adapt teaching approaches. Build tools that remember project context, team preferences, and historical decisions to provide better recommendations. ## Why Satori? Works seamlessly with Vercel AI SDK and other frameworks Built on PostgreSQL with pgvector for reliable, scalable storage Type-safe API, great DX, and comprehensive documentation ## Next Steps Get your first memory working in 5 minutes Understand how memory and embeddings work See complete implementations you can copy Dive into the complete API documentation # Quickstart Source: https://docs.usesatori.sh/quickstart Add persistent memory to your AI application in under 5 minutes ## Prerequisites Before you begin, make sure you have: * Node.js 18+ installed * An OpenAI API key ([get one here](https://platform.openai.com/api-keys)) * A Satori API key ([sign up at satori.dev](https://satori.dev)) ## Installation Install the Satori tools package along with the Vercel AI SDK: ```bash npm theme={null} npm install @usesatori/tools ai @ai-sdk/openai ``` ```bash pnpm theme={null} pnpm add @usesatori/tools ai @ai-sdk/openai ``` ```bash yarn theme={null} yarn add @usesatori/tools ai @ai-sdk/openai ``` Run `npm list @usesatori/tools` to verify the installation was successful. Create a `.env.local` file in your project root with your API keys: ```bash .env.local theme={null} OPENAI_API_KEY=sk-... SATORI_API_KEY=sk_satori_... SATORI_URL=https://api.usesatori.sh ``` Never commit your API keys to version control. Add `.env.local` to your `.gitignore` file. Create a new file `app/api/chat/route.ts` for your chat endpoint: ```typescript app/api/chat/route.ts theme={null} import { streamText } from 'ai'; import { openai } from '@ai-sdk/openai'; import { memoryTools, getContext } from '@usesatori/tools'; export async function POST(req: Request) { const { messages } = await req.json(); const userMessage = messages[messages.length - 1].content; // Create memory tools scoped to this user const tools = memoryTools({ apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId: 'user-123', // Replace with actual user ID }); // Pre-fetch relevant memories for context const memoryContext = await getContext( { apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId: 'user-123', }, userMessage, { limit: 5 } ); // Stream response with memory const result = await streamText({ model: openai('gpt-4o'), system: `You are a helpful assistant with long-term memory. What you know about this user: ${memoryContext} When the user shares important information, use the add_item tool to save it. When asked what you remember, reference the context above.`, messages, tools, }); return result.toDataStreamResponse(); } ``` Replace `'user-123'` with your actual user identifier. Each user gets their own isolated memory space. Create a simple chat UI in `app/page.tsx`: ```typescript app/page.tsx theme={null} 'use client'; import { useChat } from 'ai/react'; export default function ChatPage() { const { messages, input, handleInputChange, handleSubmit } = useChat(); return (

{messages.map((message) => (

{message.role === 'user' ? 'You' : 'Assistant'}

{message.content}

))}

); } ``` Run your Next.js development server: ```bash theme={null} npm run dev ``` Visit [http://localhost:3000](http://localhost:3000) to see your chat interface. Your application should now be running with memory-enabled chat! ## Test Your Memory Try these example conversations to see memory in action: **You:** "Remember that I prefer TypeScript over JavaScript" **Assistant:** "Got it! I'll remember that you prefer TypeScript over JavaScript." The LLM automatically calls the `add_item` tool to save this information. **You:** "My name is Alex and I'm a software engineer" **Assistant:** "Nice to meet you, Alex! I'll remember that you're a software engineer." **You:** "What do you know about me?" **Assistant:** "Based on what you've told me, I know that your name is Alex, you're a software engineer, and you prefer TypeScript over JavaScript." **You:** "Actually, I've started learning Rust and really enjoying it" **Assistant:** "That's great! I'll remember that you're learning Rust and enjoying it." ## How It Works Here's what happens behind the scenes: 1. **User sends a message** → Your API route receives the message 2. **Fetch relevant context** → `getContext()` searches for relevant memories using semantic similarity 3. **Inject into system prompt** → Memories are added to the system prompt as context 4. **LLM processes** → The model sees both the message and relevant memories 5. **Auto-save important info** → The LLM calls `add_item` tool when it detects important information 6. **Stream response** → The response streams back to the user The LLM decides when to save memories based on the conversation context. You don't need to manually parse or store information. ## Understanding User Isolation Each `userId` you provide gets completely isolated memory storage: ```typescript theme={null} // User Alice's memories const aliceTools = memoryTools({ apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId: 'alice', }); // User Bob's memories (completely separate) const bobTools = memoryTools({ apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId: 'bob', }); ``` Always use unique, consistent user identifiers. Never share the same `userId` across different users. ## Next Steps Understand embeddings, semantic search, and memory lifecycle Learn advanced patterns like streaming, error handling, and optimization Use the MemoryClient directly for custom integrations Explore the complete API documentation ## Troubleshooting Make sure your API key is correctly set in your `.env.local` file and that you've restarted your development server after adding it. ```bash theme={null} # Verify your environment variables are loaded console.log('API Key:', process.env.SATORI_API_KEY?.substring(0, 10) + '...'); ``` Check that: 1. The `tools` are passed to `streamText()` 2. Your system prompt instructs the LLM to use the `add_item` tool 3. The conversation contains information worth remembering You can also manually test memory storage using the direct client. Verify that `getContext()` is being called before `streamText()` and that the result is included in your system prompt. ```typescript theme={null} console.log('Memory context:', memoryContext); ``` Check out our comprehensive troubleshooting guide # Troubleshooting Source: https://docs.usesatori.sh/troubleshooting Common issues and solutions for Satori integration ## Common Issues **Symptoms:** * `Unauthorized - Invalid API key` error * 401 status code on API requests **Solutions:** 1. **Verify your API key is correct:** ```typescript theme={null} console.log('API Key:', process.env.SATORI_API_KEY?.substring(0, 15) + '...'); ``` 2. **Check environment variables are loaded:** ```bash theme={null} # Make sure .env.local exists cat .env.local # Restart your development server after adding env vars npm run dev ``` 3. **Verify the key format:** ```typescript theme={null} // Should start with 'sk_satori_' if (!process.env.SATORI_API_KEY?.startsWith('sk_satori_')) { console.error('Invalid API key format'); } ``` 4. **Check if the key is revoked:** * Log into your dashboard * Go to API Keys * Verify the key status is "Active" **Symptoms:** * LLM doesn't call `add_item` tool * No memories appear in database **Solutions:** 1. **Verify tools are passed to streamText:** ```typescript theme={null} const tools = memoryTools(config); const result = await streamText({ model: openai('gpt-4o'), messages, tools, // ← Make sure this is included }); ``` 2. **Check system prompt instructs LLM to save:** ```typescript theme={null} system: `You are a helpful assistant with memory. When the user shares important information, use the add_item tool to save it. Important information includes: - Personal preferences - Personal details - Goals and intentions` ``` 3. **Verify maxSteps is set:** ```typescript theme={null} const result = await streamText({ model: openai('gpt-4o'), messages, tools, maxSteps: 5, // ← Allow tool calls }); ``` 4. **Test with explicit command:** ``` User: "Remember that I love TypeScript" ``` If this doesn't work, check your API logs for errors. **Symptoms:** * LLM doesn't reference saved memories * Responses don't seem personalized **Solutions:** 1. **Verify context is fetched:** ```typescript theme={null} const context = await getContext(config, userMessage); console.log('Memory context:', context); // Should output something like: // "- User prefers TypeScript // - User loves hiking" ``` 2. **Check context is in system prompt:** ```typescript theme={null} system: `You are a helpful assistant. What you know about this user: ${memoryContext} // ← Make sure this is included Use this information to personalize responses.` ``` 3. **Verify memories exist:** ```typescript theme={null} const client = new MemoryClient(config); const all = await client.getAllMemories(); console.log('Total memories:', all.length); ``` 4. **Check search threshold:** ```typescript theme={null} // Lower threshold for broader matches const context = await getContext(config, userMessage, { threshold: 0.6, // Default is 0.7 }); ``` **Symptoms:** * `Too Many Requests` error * 429 status code **Solutions:** 1. **Implement exponential backoff:** ```typescript theme={null} async function retryWithBackoff(fn: () => Promise, maxRetries = 3) { for (let i = 0; i < maxRetries; i++) { try { return await fn(); } catch (error) { if (error.message.includes('rate limit') && i < maxRetries - 1) { const delay = Math.pow(2, i) * 1000; await new Promise(resolve => setTimeout(resolve, delay)); } else { throw error; } } } } // Usage await retryWithBackoff(() => client.addMemory('content')); ``` 2. **Batch operations:** ```typescript theme={null} // Instead of multiple individual calls const memories = ['memory1', 'memory2', 'memory3']; await Promise.all(memories.map(m => client.addMemory(m))); ``` 3. **Cache context fetches:** ```typescript theme={null} const contextCache = new Map(); async function getCachedContext(query: string) { if (contextCache.has(query)) { return contextCache.get(query)!; } const context = await getContext(config, query); contextCache.set(query, context); return context; } ``` 4. **Contact support for higher limits** **Symptoms:** * API calls take several seconds * Chat feels sluggish **Solutions:** 1. **Reduce context limit:** ```typescript theme={null} // Fetch fewer memories const context = await getContext(config, userMessage, { limit: 3, // Instead of 10 }); ``` 2. **Parallel operations:** ```typescript theme={null} // Fetch context and start LLM call in parallel const [memoryContext] = await Promise.all([ getContext(config, userMessage), // Other async operations ]); ``` 3. **Cache embeddings for common queries:** ```typescript theme={null} const embeddingCache = new Map(); async function getCachedContext(query: string) { const cacheKey = query.toLowerCase().trim(); if (embeddingCache.has(cacheKey)) { return embeddingCache.get(cacheKey); } const context = await getContext(config, query); embeddingCache.set(cacheKey, context); // Clear cache after 5 minutes setTimeout(() => embeddingCache.delete(cacheKey), 5 * 60 * 1000); return context; } ``` 4. **Use streaming:** ```typescript theme={null} // Stream responses for better perceived performance const result = await streamText({ model: openai('gpt-4o'), messages, tools, }); return result.toDataStreamResponse(); ``` **Symptoms:** * Type errors in IDE * Build fails with type errors **Solutions:** 1. **Install type definitions:** ```bash theme={null} npm install --save-dev @types/node ``` 2. **Import types correctly:** ```typescript theme={null} import type { Memory, MemoryWithSimilarity } from '@usesatori/tools'; ``` 3. **Check tsconfig.json:** ```json theme={null} { "compilerOptions": { "strict": true, "esModuleInterop": true, "skipLibCheck": true, "moduleResolution": "bundler" } } ``` 4. **Rebuild packages:** ```bash theme={null} cd packages/js-tools npm run build ``` **Symptoms:** * `CORS policy` error in browser console * Requests fail from frontend **Solutions:** 1. **Never call Satori API from frontend:** ```typescript theme={null} // ❌ Don't do this in client components 'use client'; const client = new MemoryClient({ apiKey: '...' }); // API key exposed! // ✅ Do this instead - use API routes export async function POST(req: Request) { // Server-side only const client = new MemoryClient({ apiKey: process.env.SATORI_API_KEY!, }); } ``` 2. **Use server-side API routes:** ```typescript theme={null} // app/api/memories/route.ts export async function GET() { const client = new MemoryClient({ apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId: 'user-123', }); const memories = await client.getAllMemories(); return Response.json({ memories }); } ``` **Symptoms:** * `Memory not found` when deleting * 404 errors **Solutions:** 1. **Verify memory ID:** ```typescript theme={null} // Make sure you have the correct UUID console.log('Deleting memory:', memoryId); await client.deleteMemory(memoryId); ``` 2. **Check memory belongs to user:** ```typescript theme={null} // Memory IDs are scoped per user const memories = await client.getAllMemories(); const exists = memories.some(m => m.id === memoryId); if (!exists) { console.error('Memory not found for this user'); } ``` 3. **Handle errors gracefully:** ```typescript theme={null} try { await client.deleteMemory(memoryId); } catch (error) { if (error.message.includes('Not Found')) { console.log('Memory already deleted or does not exist'); } else { throw error; } } ``` **Symptoms:** * Same information saved multiple times * Too many similar memories **Solutions:** 1. **Check before saving:** ```typescript theme={null} // Search for similar memories first const existing = await client.searchMemories(content, { threshold: 0.9, // High threshold for near-duplicates limit: 1, }); if (existing.length === 0) { await client.addMemory(content); } else { console.log('Similar memory already exists'); } ``` 2. **Update system prompt:** ```typescript theme={null} system: `Before saving a memory, consider if similar information already exists. Only save truly new or updated information.` ``` 3. **Periodic cleanup:** ```typescript theme={null} // Find and merge duplicate memories const memories = await client.getAllMemories(); for (let i = 0; i < memories.length; i++) { for (let j = i + 1; j < memories.length; j++) { const similarity = await calculateSimilarity( memories[i].content, memories[j].content ); if (similarity > 0.95) { // Keep the newer one, delete the older await client.deleteMemory(memories[i].id); break; } } } ``` ## Debugging Tips ### Enable Verbose Logging ```typescript theme={null} // Add detailed logging console.log('=== Memory Debug Info ==='); console.log('User ID:', userId); console.log('API Key:', process.env.SATORI_API_KEY?.substring(0, 15) + '...'); console.log('Base URL:', process.env.SATORI_URL); const context = await getContext(config, userMessage); console.log('Context fetched:', context); console.log('Context length:', context.length); const result = await streamText({ model: openai('gpt-4o'), system: `...${context}`, messages, tools, onFinish: (result) => { console.log('Tool calls:', result.toolCalls); console.log('Finish reason:', result.finishReason); }, }); ``` ### Test Memory Operations Directly ```typescript theme={null} // Test script to verify memory operations import { MemoryClient } from '@usesatori/tools'; async function testMemory() { const client = new MemoryClient({ apiKey: process.env.SATORI_API_KEY!, baseUrl: process.env.SATORI_URL!, userId: 'test-user', }); console.log('1. Adding memory...'); const memory = await client.addMemory('Test memory content'); console.log('✓ Memory added:', memory.id); console.log('2. Searching memories...'); const results = await client.searchMemories('test'); console.log('✓ Found', results.length, 'memories'); console.log('3. Getting all memories...'); const all = await client.getAllMemories(); console.log('✓ Total memories:', all.length); console.log('4. Deleting memory...'); await client.deleteMemory(memory.id); console.log('✓ Memory deleted'); console.log('All tests passed!'); } testMemory().catch(console.error); ``` ### Check Network Requests ```typescript theme={null} // Log all fetch requests const originalFetch = global.fetch; global.fetch = async (...args) => { console.log('Fetch:', args[0]); const response = await originalFetch(...args); console.log('Status:', response.status); return response; }; ``` ## Getting Help If you're still experiencing issues: Review the quickstart guide Report bugs or request features Get help from the community Contact our support team ## Useful Resources * [API Reference](/api-reference/introduction) * [Integration Guides](/guides/vercel-ai-sdk) * [Core Concepts](/concepts/how-it-works) * [Examples](/examples/chat-with-memory)

Your API Keys

{key.name}

All Memories ({memories.length})

{key.name}

Chat with Memory

Your Preferences

Add New Preference

Saved Preferences

Chat with Memory

Your Memories