Skip to content

Latest commit

 

History

History
176 lines (124 loc) · 4.53 KB

README.md

File metadata and controls

176 lines (124 loc) · 4.53 KB

ElizaOS PostgreSQL Adapter

A database adapter plugin for ElizaOS that provides PostgreSQL connectivity with vector embedding support for semantic search capabilities.

Features

  • Seamless integration with ElizaOS memory and knowledge storage systems
  • Vector embedding storage and retrieval with pgvector extension
  • Support for multiple embedding models and dimensions (OpenAI, Ollama, GaiaNet)
  • Robust connection management with automatic retries and circuit breaking
  • Full transaction support for safe database operations
  • Comprehensive memory, relationship, and knowledge management
  • Built-in caching system

Prerequisites

  • PostgreSQL 15+ with pgvector extension installed
  • Connection permissions to create tables and extensions

Installation

Install the adapter via npm:

npm install @elizaos-plugins/adapter-postgres

Or using pnpm:

pnpm add @elizaos-plugins/adapter-postgres

Configuration

Add the adapter to your ElizaOS configuration and provide the necessary connection details:

// agent.config.js
export default {
  // Other ElizaOS configuration
  adapters: ["postgres"],
  // PostgreSQL connection environment variables
  settings: {
    POSTGRES_URL: "postgresql://username:password@localhost:5432/elizaos"
  }
}

Environment Variables

  • POSTGRES_URL - Required PostgreSQL connection string

Database Schema

The adapter automatically initializes the required database schema when first connecting, including:

  • Setting up the pgvector extension
  • Creating all necessary tables (memories, accounts, rooms, etc.)
  • Configuring indexes for vector search

The schema includes tables for:

  • accounts - User and agent profiles
  • rooms - Conversation containers
  • memories - Messages and other memory objects with vector embeddings
  • goals - User and agent goals
  • participants - Room participation records
  • relationships - Connections between accounts
  • knowledge - Agent knowledge base with vector embeddings
  • cache - Key-value cache storage

Vector Search

The adapter uses pgvector to provide semantic search through vector embeddings, supporting:

  • Multiple embedding models (OpenAI, Ollama, GaiaNet, etc.)
  • Automatic dimension detection (1536 for OpenAI, 1024 for Ollama, etc.)
  • Cosine similarity search with configurable thresholds
  • Text-based keyword search with Levenshtein distance

Memory Management

The adapter provides methods for:

// Creating memories with vector embeddings
await adapter.createMemory(memory, tableName);

// Searching memories by vector similarity
await adapter.searchMemoriesByEmbedding(embedding, options);

// Retrieving memories by various criteria
await adapter.getMemories({ roomId, tableName, count, unique });

Knowledge Management

For agent knowledge base management:

// Store knowledge items with vector embeddings
await adapter.createKnowledge(knowledgeItem);

// Search knowledge by vector similarity and text
await adapter.searchKnowledge({
  agentId,
  embedding, 
  match_threshold: 0.8,
  match_count: 10,
  searchText: "optional text"
});

// Remove knowledge
await adapter.removeKnowledge(knowledgeId);

Caching System

The adapter includes a built-in caching system:

// Store cache values
await adapter.setCache({ key, agentId, value });

// Retrieve cached values
const value = await adapter.getCache({ key, agentId });

// Delete cache entries
await adapter.deleteCache({ key, agentId });

Connection Management

The adapter implements robust connection handling:

  • Circuit breaker pattern to prevent cascading failures
  • Automatic connection retry with exponential backoff
  • Connection pooling with configurable limits
  • Graceful connection cleanup on shutdown

Development

Testing

The repository includes a comprehensive test suite:

# Run tests with Docker for pgvector support
cd src/__tests__
./run_tests.sh

Tests require Docker to spin up a PostgreSQL instance with pgvector support.

Building

pnpm build

Troubleshooting

Common Issues

  1. Connection errors:

    • Verify your PostgreSQL connection string
    • Ensure PostgreSQL is running and accessible
    • Check network connectivity and firewall settings

  2. Vector search issues:

    • Verify pgvector extension is installed in your PostgreSQL database
    • Ensure embedding dimensions match your model

  3. Permission errors:

    • The database user needs permission to create extensions and tables
    • For production, consider using a more restricted user after initialization