add Qdrant vectordb support

[vincentsunx]

Description

Add Qdrant as a VectorDB backend for OpenViking, enabling OpenViking memory storage and retrieval through Qdrant. This PR includes a REST-based Qdrant collection implementation, adapter registration, backend configuration support, sidecar metadata handling, and tests for Qdrant-specific behavior.

Related Issue

N/A

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Test update

Changes Made

• Added a Qdrant ICollection implementation using Qdrant REST APIs, without requiring qdrant-client.
• Added support for dense vector search, sparse/hybrid search, scalar filtering, keyword search, fetch, upsert, delete, count, and index-related operations.
• Added deterministic mapping from OpenViking arbitrary IDs to Qdrant-compatible point IDs while preserving original IDs in payload.
• Added sidecar metadata persistence in Qdrant for OpenViking collection/index metadata.
• Added Qdrant VectorDB adapter and registered it in the VectorDB adapter factory.
• Added Qdrant backend configuration support, including URL, API key, timeout, vector names, metadata collection name, text index toggle, dimension, distance metric, and collection name.
• Added Qdrant-specific path scope support by normalizing URI fields and maintaining internal path fields for recursive retrieval.
• Added safeguards for missing metadata, failed metadata writes, stale physical collections, and cleanup/drop behavior.
• Added tests covering Qdrant adapter behavior, metadata store behavior, ID mapping, sparse vector handling, collection lifecycle, CRUD/search/filter paths, and Qdrant integration behavior.

Testing

• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have tested this on the following platforms:
  • Linux
  • macOS
  • Windows

Tested locally on Windows with:

• py_compile for modified Python files
• Local Qdrant container at localhost:6333
• OpenViking started from current source
• OpenClaw + OpenViking + Qdrant end-to-end LoCoMo small run

LoCoMo small result:

Overall accuracy: 32/35 = 91.43%
Qdrant collection: context_volcengine
Qdrant points count: 33
OpenViking extracted memories: 21

Token usage:

QA total tokens: 878,436
OpenViking LLM total tokens: 52,875
Embedding tokens: 10,376

Checklist

• My code follows the project's coding style
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• Any dependent changes have been merged and published

Screenshots (if applicable)

Additional Notes

Qdrant is treated as an optional backend dependency. Users need qdrant-client installed when using backend: qdrant.

Example VectorDB config:

{
  "backend": "qdrant",
  "name": "context_volcengine",
  "project": "default",
  "index_name": "default",
  "url": "http://127.0.0.1:6333",
  "dimension": 1024,
  "distance_metric": "cosine",
  "qdrant": {
    "timeout_seconds": 10,
    "dense_vector_name": "vector",
    "sparse_vector_name": "sparse_vector",
    "meta_collection_name": "__openviking_meta",
    "enable_text_index": true
  }
}

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪

🏅 Score: 85

🧪 PR contains tests

🔒 No security concerns identified

✅ No TODO sections

🔀 No multiple PR themes

⚡ Recommended focus areas for review Dead code The method _convert_search_results is defined but never called in the codebase. def _convert_search_results(self, results) -> SearchResult: """Convert Qdrant search results to OpenViking SearchResult.""" data = [] for point in results: payload = point.payload or {} # Use original ID from payload if available original_id = payload.pop(self.ORIGINAL_ID_FIELD, None) or str(point.id) payload["id"] = original_id data.append(SearchItemResult( id=original_id, fields=payload, score=point.score, )) return SearchResult(data=data)

[github-actions]

PR Code Suggestions ✨

No code suggestions found for the PR.

[vincentsunx]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪
🏅 Score: 85
🧪 PR contains tests
🔒 No security concerns identified
✅ No TODO sections
🔀 No multiple PR themes
⚡ Recommended focus areas for review

Dead code
The method _convert_search_results is defined but never called in the codebase.

def _convert_search_results(self, results) -> SearchResult:
    """Convert Qdrant search results to OpenViking SearchResult."""
    data = []
    for point in results:
        payload = point.payload or {}
        # Use original ID from payload if available
        original_id = payload.pop(self.ORIGINAL_ID_FIELD, None) or str(point.id)
        payload["id"] = original_id
        data.append(SearchItemResult(
            id=original_id,
            fields=payload,
            score=point.score,
        ))
    return SearchResult(data=data)

Dead code ”def _convert_search_results“ has been removed.