API Reference

Souvenir provides a simple API focused on tools for Vercel AI SDK agents.

Memory Tools (Main API)

The primary way to use Souvenir is through the memory tools:

Memory Tools

Pre-built tools for Vercel AI SDK agents that handle all memory operations automatically:

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

const tools = createSouvenirTools(souvenir);

// Use in your agent
await generateText({
  model: openai('gpt-4'),
  tools, // Provides: storeMemory, searchMemory, deleteMemory
  messages: [...]
});

Available tools:

• storeMemory - Store important information in memory
• searchMemory - Search past memories with configurable retrieval strategies
• deleteMemory - Delete specific memories by node ID

storeMemory

Store information in long-term memory for later recall.

Parameters:

• content (string) - The information to store in memory
• metadata (object, optional) - Additional context or tags

Returns:

{
  success: boolean;
  chunkIds: string[];
  message: string;
}

searchMemory

Search long-term memory for relevant information.

Parameters:

• query (string) - What to search for
• explore (boolean, optional, default: true) - Explore knowledge graph

Returns:

{
  success: boolean;
  memory: string;         // LLM-consumable formatted results with <memory-node id="..."/> tags
  message: string;
  metadata: {
    query: string;
    explored: boolean;
    resultCount: number;
  };
}

Memory Format: Search results include node IDs for deletion:

# Memory Search Results

Found 2 relevant memories:

## Memory 1 (relevance: 95%)

<memory-node id="node-uuid-123" />

User prefers dark mode for all interfaces

**Context**:
- category: preference
- timestamp: 2024-01-15

deleteMemory

Delete specific memories from long-term storage.

Parameters:

• nodeIds (string[]) - Array of memory node IDs to delete (extracted from search results)

Returns:

{
  success: boolean;
  deletedCount: number;
  message: string;
}

Example:

// Search for outdated information
const searchResult = await tools.searchMemory.execute({
  query: 'old pricing information'
});

// Extract node IDs from the memory text
const idPattern = /<memory-node id="([^"]+)" \/>/g;
const nodeIds = Array.from(
  searchResult.memory.matchAll(idPattern),
  match => match[1]
);

// Delete the memories
await tools.deleteMemory.execute({ nodeIds });

---

Configuration

See the Quick Start Guide for complete configuration options.

Basic Setup

const souvenir = new Souvenir(
  {
    databaseUrl: string;              // PostgreSQL connection
    embeddingDimensions?: number;     // Default: 1536
    chunkSize?: number;               // Default: 1000
    chunkOverlap?: number;            // Default: 200
    minRelevanceScore?: number;       // Default: 0.7
    maxResults?: number;              // Default: 10
  },
  {
    sessionId: string;                // Required: session identifier (any string, max 255 chars)
    embeddingProvider: EmbeddingProvider; // Required: embedding model
    processorModel?: LanguageModel;   // Optional: entity extraction LLM
    promptTemplates?: PromptTemplates; // Optional: custom prompts
  }
);

---

Core Methods (Advanced)

For advanced use cases, the following methods are available:

search(query, options?)

Low-level search with strategy selection.

getNeighborhood(nodeId, options?)

Get nodes connected to a specific memory node.

findPaths(startNodeId, endNodeId, options?)

Find connection paths between two memories.

findClusters(sessionId?, minClusterSize?)

Discover clusters of related memories.

---

See also

• Quick Start - Get started in 5 minutes
• Retrieval Strategies - Search methods
• Chunking - Text chunking options