Installation

Prerequisites

Before installing Souvenir, ensure you have:

• Node.js 20+, Bun, or Deno
• PostgreSQL with pgvector extension
• An embedding provider (OpenAI, Cohere, or custom)

Install Package

npm install @upstart.gg/souvenir ai zod

Database Setup

1. Install PostgreSQL

If you don't have PostgreSQL installed:

brew install postgresql@16
brew services start postgresql@16

2. Install pgvector

Install the pgvector extension:

brew install pgvector

3. Create Database

createdb souvenir

Or via SQL:

CREATE DATABASE souvenir;

4. Run Migrations

Souvenir uses dbmate for migrations. Install it:

brew install dbmate

Run the migrations:

cd node_modules/@upstart.gg/souvenir
dbmate -d db/migrations -u "postgresql://localhost:5432/souvenir?sslmode=disable" up

Or manually execute the SQL from node_modules/@upstart.gg/souvenir/db/migrations/.

Verify Installation

Create a test file to verify everything works:

import { Souvenir } from '@upstart.gg/souvenir';

const souvenir = new Souvenir({
  databaseUrl: 'postgresql://localhost:5432/souvenir?sslmode=disable',
  embeddingDimensions: 1536,
  chunkSize: 1000,
  chunkOverlap: 200,
});

console.log('Souvenir initialized successfully!');

await souvenir.close();

Run it:

node --loader ts-node/esm test.ts

If you see "Souvenir initialized successfully!", you're ready to go!

Next Steps

• Quick Start - Build your first memory-enabled agent
• Configuration - Learn about configuration options