Skip to main content

Qdrant Adapter for ElizaOS

A vector database adapter for ElizaOS that provides efficient similarity search capabilities through Qdrant, optimized for knowledge management and semantic search operations.

Features​

  • Vector similarity search with cosine distance
  • Efficient knowledge base management
  • Built-in text preprocessing for better search quality
  • UUID v5 compatibility for Qdrant IDs
  • In-memory caching system
  • Content metadata support
  • Shared knowledge management

Prerequisites​

  • Qdrant server (self-hosted or cloud)
  • Node.js 23 or later
  • ElizaOS installation

Installation​

npm install @elizaos-plugins/adapter-qdrant

Configuration​

Add the adapter to your ElizaOS configuration:

{
  "plugins": ["@elizaos-plugins/adapter-qdrant"],
  "settings": {
    "QDRANT_URL": "your-qdrant-server-url",
    "QDRANT_KEY": "your-qdrant-api-key",
    "QDRANT_PORT": "6333",
    "QDRANT_VECTOR_SIZE": "1536" // Adjust based on your embedding size
  }
}

Required Environment Variables​

  • QDRANT_URL: URL of your Qdrant server
  • QDRANT_KEY: API key for authentication
  • QDRANT_PORT: Port number for Qdrant server
  • QDRANT_VECTOR_SIZE: Dimension of your vectors

Features in Detail​

The adapter provides specialized vector search capabilities:

  • Cosine similarity search
  • Configurable vector dimensions
  • Support for multiple embedding types
  • Cache support for frequent searches

Knowledge Management​

Knowledge items are stored with:

  • Vector embeddings for similarity search
  • Metadata support for additional information
  • Shared/private knowledge separation
  • Content versioning through chunk management

Text Preprocessing​

Built-in text preprocessing for better search quality:

  • Code block removal
  • URL normalization
  • Markdown cleanup
  • Special character handling
  • Whitespace normalization

Caching System​

Efficient in-memory caching:

  • Per-agent cache isolation
  • UUID-based cache keys
  • Automatic cache management

Usage Notes​

Specialized Functions​

This adapter primarily implements:

  • Knowledge management
  • Vector similarity search
  • Caching operations

Other database functions (like memory management, participant tracking, etc.) are stubbed but not implemented. Use a different adapter if you need these features.

Collection Management​

The adapter automatically manages:

  • Collection creation
  • Vector indexes
  • Point upserts with payload

Best Practices​

  1. Set correct vector dimensions based on your embedding model
  2. Use consistent embedding generation
  3. Consider caching for frequent searches
  4. Monitor memory usage with large cache sizes

FAQ​

Can I use different vector sizes?​

Yes, configure QDRANT_VECTOR_SIZE based on your embedding model's output size.

Is caching required?​

No, caching is optional but recommended for performance when doing repeated searches.

Can I share knowledge between agents?​

Yes, use the isShared flag in knowledge metadata for shared content.

How do I handle different embedding models?​

Configure the vector size to match your model's output dimensions and ensure consistent preprocessing.

Does it support multi-tenancy?​

Yes, through per-agent isolation of knowledge and cache.

What about full-text search?​

The adapter focuses on vector similarity search; use MongoDB or PostgreSQL adapters for full-text search.

Is sharding supported?​

Yes, through Qdrant's native sharding capabilities.