Mem0 Python Integration

Configure Mem0 to store searchable memories in Oracle AI Database using the Python oracledb provider.

Contents

Requirements

Use Oracle AI Database 23.4 or later with a user that can create tables and vector indexes. Install the python-oracledb driver. Thick mode also requires Oracle Client 23.4 or later.

Use an embedding model whose vector dimension matches embedding_model_dims. The default dimension is 1536.

Oracle returns a distance from VECTOR_DISTANCE. Mem0 converts the distance to a score where higher values indicate greater similarity.

Install the Packages

pip install mem0ai oracledb

Quick Start

Install the packages, configure the Oracle vector store, and add a memory. The Configure Oracle AI Vector Search section provides the complete example.

Configure Oracle AI Vector Search

Set provider to oracledb and provide Oracle connection parameters. Mem0 creates the collection table and an HNSW vector index by default.

import os

from mem0 import Memory

os.environ["OPENAI_API_KEY"] = "<your-openai-api-key>"

config = {
    "vector_store": {
        "provider": "oracledb",
        "config": {
            "collection_name": "mem0",
            "embedding_model_dims": 1536,
            "connection_params": {
                "user": "mem0_user",
                "password": "<password>",
                "dsn": "localhost:1521/FREEPDB1",
            },
        },
    },
}

memory = Memory.from_config(config)
messages = [
    {"role": "user", "content": "I enjoy science-fiction movies."},
    {"role": "assistant", "content": "I will suggest science-fiction movies in the future."},
]
memory.add(messages, user_id="alice", metadata={"category": "movies"})

Set OPENAI_API_KEY when your Mem0 configuration uses OpenAI models. Configure a different Mem0 language model or embedding provider when your application does not use OpenAI.

Connect to Oracle AI Database

Pass an existing oracledb.Connection or oracledb.ConnectionPool as client when your application manages its own Oracle connections.

import oracledb

from mem0 import Memory

pool = oracledb.create_pool(
    user="mem0_user",
    password="<password>",
    dsn="localhost:1521/FREEPDB1",
)

config = {
    "vector_store": {
        "provider": "oracledb",
        "config": {"client": pool},
    },
}

memory = Memory.from_config(config)

When you provide client, Mem0 ignores connection_params and use_connection_pool. Mem0 does not close a connection or pool that your application created.

Create HNSW and IVF Indexes

Set index_type to HNSW or IVF, and set index_parameters for the selected index type. Set do_create_index to false when you want exact search or manage the index yourself.

config = {
    "vector_store": {
        "provider": "oracledb",
        "config": {
            "connection_params": {
                "user": "mem0_user",
                "password": "<password>",
                "dsn": "localhost:1521/FREEPDB1",
            },
            "index_type": "HNSW",
            "index_parameters": {
                "neighbors": 32,
                "efconstruction": 200,
            },
            "index_accuracy": 95,
        },
    },
}

Use neighbors and efconstruction for HNSW indexes. For IVF indexes, use neighbor partitions, samples_per_partition, and min_vectors_per_partition.

Filter Memories by Metadata

Use metadata filters to limit memory retrieval to records that match application context. Mem0 combines fields in filters with AND.

results = memory.search(
    "movie recommendations",
    filters={
        "user_id": "alice",
        "category": {"in": ["movies", "books"]},
        "rating": {"gte": 4},
    },
)

Mem0 supports the following filters against the JSON payload column:

Filter type Example
Scalar equality {"user_id": "alice"}
Field existence {"agent_id": "*"}
Comparison {"score": {"gte": 0.5}}; also eq, ne, gt, lt, and lte
Membership {"category": {"in": ["movies", "books"]}}; also nin
String matching {"title": {"contains": "sci-fi"}}; also icontains for case-insensitive matching
Logical groups {"AND": [...]}, {"OR": [...]}, and {"NOT": [...]}

Multiple fields in filters are combined with AND.

Interpret Search Scores

Oracle returns a distance from VECTOR_DISTANCE, which Mem0 converts to a score where higher values indicate greater similarity. Scores from COSINE and other non-negative metrics range from 0 through 1. DOT returns the inner product, so its scores can fall outside that range.

Review Configuration Options

Provide either connection_params or an existing connection or pool as client.

Option Description Default
connection_params Oracle connection settings, such as user, password, and dsn. Required unless client is provided. None
use_connection_pool Creates a connection pool from connection_params. true
client Existing oracledb.Connection or oracledb.ConnectionPool. Required unless connection_params is provided. None
collection_name Oracle table that stores vectors and JSON payloads. mem0
embedding_model_dims Dimension of embedding vectors. 1536
distance_metric Index and search distance metric: COSINE, EUCLIDEAN, EUCLIDEAN_SQUARED, DOT, HAMMING, or MANHATTAN. COSINE
do_create_index Creates a vector index for the collection. true
index_type Vector index type: HNSW or IVF. HNSW
index_name Name of the vector index. <collection_name>_VEC_IDX
index_parameters Tuning parameters. HNSW uses neighbors and efconstruction. IVF uses neighbor partitions, samples_per_partition, and min_vectors_per_partition. None
index_accuracy Target index accuracy from 1 through 100, applied as WITH TARGET ACCURACY <n>. None

Reference Links