Skip to main content

Prerequisites

Before you begin, make sure you have:

Installation

1

Install dependencies

Install the Satori tools package along with the Vercel AI SDK:
Run npm list @usesatori/tools to verify the installation was successful.
2

Set up environment variables

Create a .env.local file in your project root with your API keys:
.env.local
Never commit your API keys to version control. Add .env.local to your .gitignore file.
3

Create your first memory-enabled chat

Create a new file app/api/chat/route.ts for your chat endpoint:
app/api/chat/route.ts
Replace 'user-123' with your actual user identifier. Each user gets their own isolated memory space.
4

Create a chat interface

Create a simple chat UI in app/page.tsx:
app/page.tsx
5

Start your application

Run your Next.js development server:
Visit 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 contextgetContext() 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:
Always use unique, consistent user identifiers. Never share the same userId across different users.

Next Steps

Learn How It Works

Understand embeddings, semantic search, and memory lifecycle

Advanced Integration

Learn advanced patterns like streaming, error handling, and optimization

Direct Client Usage

Use the MemoryClient directly for custom integrations

API Reference

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.
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.

Need more help?

Check out our comprehensive troubleshooting guide