Description

Integrates Turbopuffer as a vector database provider for mem0.

• Adds TurbopufferDB vector store implementation using the official turbopuffer Python SDK (v1.19+)
• Adds TurbopufferConfig Pydantic config class
• Registers the provider in VectorStoreFactory and VectorStoreConfig
• Adds documentation page and navigation entries

Fixes #2543

Type of change

• New feature (non-breaking change which adds functionality)

Implementation Details

• Uses the new Turbopuffer client API (not the legacy tpuf.api_key global pattern)
• insert() uses row-based namespace.write(upsert_rows=...) with batching
• update() with vector=None uses patch_rows for payload-only updates (avoids corrupting existing vectors)
• delete() uses namespace.write(deletes=[id])
• delete_col() uses namespace.delete_all()
• search() uses namespace.query(rank_by=("vector", "ANN", ...)) with native filter support
• get() uses ANN query with ID filter (turbopuffer applies filters before ranking, guaranteeing correctness)
• list() returns wrapped [results] format for compatibility with main.py's _get_all_from_vector_store and delete_all
• count() uses namespace.metadata().approx_row_count instead of querying with top_k=10000
• col_info() uses namespace.metadata() for real namespace stats
• _parse_output() correctly extracts $dist and attributes from turbopuffer Row objects via model_dump()
• Score conversion: 1 - cosine_distance = cosine_similarity (mathematically correct for [0, 2] range)
• Payload key collision protection: id/vector are set after payload.update() to prevent overwrites
• region defaults to gcp-us-central1 (required by the turbopuffer SDK)
• Graceful error handling for list_cols(), list(), delete_col(), col_info(), get(), and count() when namespace doesn't exist or permissions are limited

Testing

Testing Methodology

The integration was validated through two layers of testing:

1. Unit Tests (64 tests) — mocked SDK

All turbopuffer SDK calls are mocked, testing every method in isolation with edge cases. Tests use real turbopuffer.types.Row objects (via model_validate) to ensure _parse_output handles the actual SDK data model correctly. Tests are skipped via pytest.importorskip when the SDK is not installed (CI compatibility).

2. End-to-End Tests (12 tests) — real turbopuffer API

Ran against the live turbopuffer API to validate real behavior. This caught two issues that unit tests could not:

• list_cols() returns 403 when the API key lacks namespace listing permissions → added graceful error handling
• list() after reset() returns 404 because the namespace no longer exists → added try/except
• Confirmed that patch_rows (payload-only update) truly preserves the original vector by searching with the old vector after patching

Unit Test Coverage

E2E Test Results (against real turbopuffer API)

Regression Testing

No regressions in existing tests:

• Qdrant tests: 19/19 passed
• Safe deepcopy config tests: 94/94 passed

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• 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

Maintainer Checklist

• closes Integrate turbopuffer as a vector database #2543
• Made sure Checks passed

🤖 Generated with Claude Code