Skip to main content

MongoDB Adapter for ElizaOS

A robust MongoDB adapter for ElizaOS that provides persistence, vector search capabilities, and caching functionality.

Features​

  • Full MongoDB database support with connection pooling
  • Vector search capabilities for efficient similarity searches
  • Automatic fallback to standard search when vector search is unavailable
  • Built-in caching system with TTL support
  • Sharding support for better performance at scale
  • Comprehensive memory and knowledge management
  • Relationship tracking between users
  • Goal tracking and management
  • Participant and room management

Prerequisites​

  • MongoDB 6.0 or later (recommended for vector search support)
  • NodeJS 16.0 or later
  • ElizaOS installation

Installation​

npm install @elizaos-plugins/adapter-mongodb

Configuration​

Add the adapter to your ElizaOS configuration:

{
  "plugins": ["@elizaos-plugins/adapter-mongodb"],
  "settings": {
    "MONGODB_CONNECTION_STRING": "your_mongodb_connection_string",
    "MONGODB_DATABASE": "your_database_name" // Optional, defaults to "elizaAgent"
  }
}

Required Environment Variables​

  • MONGODB_CONNECTION_STRING: Your MongoDB connection string
  • MONGODB_DATABASE (optional): Database name to use

Connection Options​

The adapter is configured with optimal connection settings:

  • Maximum pool size: 100 connections
  • Minimum pool size: 5 connections
  • Connection timeout: 10 seconds
  • Socket timeout: 45 seconds
  • Retry support for both reads and writes
  • Compression enabled (zlib)

Features in Detail​

The adapter automatically detects and enables vector search capabilities if your MongoDB instance supports it. This provides efficient similarity searches for:

  • Memory retrieval
  • Knowledge base searches
  • Semantic similarity matching

If vector search is unavailable, the adapter automatically falls back to standard search methods.

Caching​

Built-in caching system with:

  • 24-hour TTL by default
  • Automatic cache invalidation
  • Memory-efficient storage
  • Cache hit/miss optimizations

Memory Management​

Comprehensive memory management features:

  • CRUD operations for memories
  • Vector-based similarity search
  • Batch processing support
  • Automatic uniqueness checking

Knowledge Base​

Robust knowledge base management:

  • Support for shared and private knowledge
  • Vector-based knowledge retrieval
  • Metadata support
  • Chunk management for large content

Development​

Running Tests​

The test suite uses Docker for running a test MongoDB instance:

cd src/__tests__
./run_tests.sh

This will:

  1. Start a MongoDB container
  2. Run the test suite
  3. Clean up resources automatically

Contributing​

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Submit a pull request

Error Handling​

The adapter includes comprehensive error handling:

  • Connection failure recovery
  • Automatic reconnection
  • Graceful degradation of vector search
  • Detailed error logging

Performance Considerations​

  • Uses connection pooling for optimal performance
  • Implements efficient batch processing
  • Supports sharding for horizontal scaling
  • Includes index optimization