Add Apache Cassandra vector store support (#3578)

Author: faizan842

docs/components/vectordbs/dbs/cassandra.mdx

@@ -0,0 +1,181 @@
+---
+title: Apache Cassandra
+---
+
+[Apache Cassandra](https://cassandra.apache.org/) is a highly scalable, distributed NoSQL database designed for handling large amounts of data across many commodity servers with no single point of failure. It supports vector storage for semantic search capabilities in AI applications and can scale to massive datasets with linear performance improvements.
+
+### Usage
+
+```python
+import os
+from mem0 import Memory
+
+os.environ["OPENAI_API_KEY"] = "sk-xx"
+
+config = {
+    "vector_store": {
+        "provider": "cassandra",
+        "config": {
+            "contact_points": ["127.0.0.1"],
+            "port": 9042,
+            "username": "cassandra",
+            "password": "cassandra",
+            "keyspace": "mem0",
+            "collection_name": "memories",
+        }
+    }
+}
+
+m = Memory.from_config(config)
+messages = [
+    {"role": "user", "content": "I'm planning to watch a movie tonight. Any recommendations?"},
+    {"role": "assistant", "content": "How about thriller movies? They can be quite engaging."},
+    {"role": "user", "content": "I'm not a big fan of thriller movies but I love sci-fi movies."},
+    {"role": "assistant", "content": "Got it! I'll avoid thriller recommendations and suggest sci-fi movies in the future."}
+]
+m.add(messages, user_id="alice", metadata={"category": "movies"})
+```
+
+#### Using DataStax Astra DB
+
+For managed Cassandra with DataStax Astra DB:
+
+```python
+config = {
+    "vector_store": {
+        "provider": "cassandra",
+        "config": {
+            "contact_points": ["dummy"],  # Not used with secure connect bundle
+            "username": "token",
+            "password": "AstraCS:...",  # Your Astra DB application token
+            "keyspace": "mem0",
+            "collection_name": "memories",
+            "secure_connect_bundle": "/path/to/secure-connect-bundle.zip"
+        }
+    }
+}
+```
+
+<Note>
+When using DataStax Astra DB, provide the secure connect bundle path. The contact_points parameter is ignored when a secure connect bundle is provided.
+</Note>
+
+### Config
+
+Here are the parameters available for configuring Apache Cassandra:
+
+| Parameter | Description | Default Value |
+| --- | --- | --- |
+| `contact_points` | List of contact point IP addresses | Required |
+| `port` | Cassandra port | `9042` |
+| `username` | Database username | `None` |
+| `password` | Database password | `None` |
+| `keyspace` | Keyspace name | `"mem0"` |
+| `collection_name` | Table name for storing vectors | `"memories"` |
+| `embedding_model_dims` | Dimensions of embedding vectors | `1536` |
+| `secure_connect_bundle` | Path to Astra DB secure connect bundle | `None` |
+| `protocol_version` | CQL protocol version | `4` |
+| `load_balancing_policy` | Custom load balancing policy | `None` |
+
+### Setup
+
+#### Option 1: Local Cassandra Setup using Docker:
+
+```bash
+# Pull and run Cassandra container
+docker run --name mem0-cassandra \
+    -p 9042:9042 \
+    -e CASSANDRA_CLUSTER_NAME="Mem0Cluster" \
+    -d cassandra:latest
+
+# Wait for Cassandra to start (may take 1-2 minutes)
+docker exec -it mem0-cassandra cqlsh
+
+# Create keyspace
+CREATE KEYSPACE IF NOT EXISTS mem0
+WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1};
+```
+
+#### Option 2: DataStax Astra DB (Managed Cloud):
+
+1. Sign up at [DataStax Astra](https://astra.datastax.com/)
+2. Create a new database
+3. Download the secure connect bundle
+4. Generate an application token
+
+<Tip>
+For production deployments, use DataStax Astra DB for fully managed Cassandra with automatic scaling, backups, and security.
+</Tip>
+
+#### Option 3: Install Cassandra Locally:
+
+**Ubuntu/Debian:**
+```bash
+# Add Apache Cassandra repository
+echo "deb https://downloads.apache.org/cassandra/debian 40x main" | sudo tee -a /etc/apt/sources.list.d/cassandra.sources.list
+curl https://downloads.apache.org/cassandra/KEYS | sudo apt-key add -
+
+# Install Cassandra
+sudo apt-get update
+sudo apt-get install cassandra
+
+# Start Cassandra
+sudo systemctl start cassandra
+
+# Verify installation
+nodetool status
+```
+
+**macOS:**
+```bash
+# Using Homebrew
+brew install cassandra
+
+# Start Cassandra
+brew services start cassandra
+
+# Connect to CQL shell
+cqlsh
+```
+
+### Python Client Installation
+
+Install the required Python package:
+
+```bash
+pip install cassandra-driver
+```
+
+### Performance Considerations
+
+- **Replication Factor**: For production, use replication factor of at least 3
+- **Consistency Level**: Balance between consistency and performance (QUORUM recommended)
+- **Partitioning**: Cassandra automatically distributes data across nodes
+- **Scaling**: Add nodes to linearly increase capacity and performance
+
+### Advanced Configuration
+
+```python
+from cassandra.policies import DCAwareRoundRobinPolicy
+
+config = {
+    "vector_store": {
+        "provider": "cassandra",
+        "config": {
+            "contact_points": ["node1.example.com", "node2.example.com", "node3.example.com"],
+            "port": 9042,
+            "username": "mem0_user",
+            "password": "secure_password",
+            "keyspace": "mem0_prod",
+            "collection_name": "memories",
+            "protocol_version": 4,
+            "load_balancing_policy": DCAwareRoundRobinPolicy(local_dc='DC1')
+        }
+    }
+}
+```
+
+<Warning>
+For production use, configure appropriate replication strategies and consistency levels based on your availability and consistency requirements.
+</Warning>
+

docs/docs.json

@@ -59,7 +59,7 @@
 												"icon": "star",
 												"pages": [
 													"platform/features/platform-overview",
-                          "platform/features/v2-memory-filters",
+													"platform/features/v2-memory-filters",
 													"platform/features/contextual-add",
 													"platform/features/async-client",
 													"platform/features/async-mode-default-change",
@@ -153,6 +153,7 @@
 														"pages": [
 															"components/vectordbs/dbs/qdrant",
 															"components/vectordbs/dbs/chroma",
+															"components/vectordbs/dbs/cassandra",
 															"components/vectordbs/dbs/pgvector",
 															"components/vectordbs/dbs/milvus",
 															"components/vectordbs/dbs/pinecone",

mem0/configs/vector_stores/cassandra.py

@@ -0,0 +1,77 @@
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class CassandraConfig(BaseModel):
+    """Configuration for Apache Cassandra vector database."""
+
+    contact_points: List[str] = Field(
+        ...,
+        description="List of contact point addresses (e.g., ['127.0.0.1', '127.0.0.2'])"
+    )
+    port: int = Field(9042, description="Cassandra port")
+    username: Optional[str] = Field(None, description="Database username")
+    password: Optional[str] = Field(None, description="Database password")
+    keyspace: str = Field("mem0", description="Keyspace name")
+    collection_name: str = Field("memories", description="Table name")
+    embedding_model_dims: int = Field(1536, description="Dimensions of the embedding model")
+    secure_connect_bundle: Optional[str] = Field(
+        None,
+        description="Path to secure connect bundle for DataStax Astra DB"
+    )
+    protocol_version: int = Field(4, description="CQL protocol version")
+    load_balancing_policy: Optional[Any] = Field(
+        None,
+        description="Custom load balancing policy object"
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def check_auth(cls, values: Dict[str, Any]) -> Dict[str, Any]:
+        """Validate authentication parameters."""
+        username = values.get("username")
+        password = values.get("password")
+
+        # Both username and password must be provided together or not at all
+        if (username and not password) or (password and not username):
+            raise ValueError(
+                "Both 'username' and 'password' must be provided together for authentication"
+            )
+
+        return values
+
+    @model_validator(mode="before")
+    @classmethod
+    def check_connection_config(cls, values: Dict[str, Any]) -> Dict[str, Any]:
+        """Validate connection configuration."""
+        secure_connect_bundle = values.get("secure_connect_bundle")
+        contact_points = values.get("contact_points")
+
+        # Either secure_connect_bundle or contact_points must be provided
+        if not secure_connect_bundle and not contact_points:
+            raise ValueError(
+                "Either 'contact_points' or 'secure_connect_bundle' must be provided"
+            )
+
+        return values
+
+    @model_validator(mode="before")
+    @classmethod
+    def validate_extra_fields(cls, values: Dict[str, Any]) -> Dict[str, Any]:
+        """Validate that no extra fields are provided."""
+        allowed_fields = set(cls.model_fields.keys())
+        input_fields = set(values.keys())
+        extra_fields = input_fields - allowed_fields
+
+        if extra_fields:
+            raise ValueError(
+                f"Extra fields not allowed: {', '.join(extra_fields)}. "
+                f"Please input only the following fields: {', '.join(allowed_fields)}"
+            )
+
+        return values
+
+    class Config:
+        arbitrary_types_allowed = True
+

mem0/utils/factory.py

@@ -184,6 +184,7 @@ class VectorStoreFactory:
         "langchain": "mem0.vector_stores.langchain.Langchain",
         "s3_vectors": "mem0.vector_stores.s3_vectors.S3Vectors",
         "baidu": "mem0.vector_stores.baidu.BaiduDB",
+        "cassandra": "mem0.vector_stores.cassandra.CassandraDB",
         "neptune": "mem0.vector_stores.neptune_analytics.NeptuneAnalyticsVector",
     }