Metadata-Version: 2.4
Name: mem0-falkordb
Version: 0.4.1
Summary: FalkorDB graph store plugin for Mem0
Author: mem0-falkordb contributors
License-Expression: MIT
License-File: LICENSE
Keywords: ai,falkordb,graph,mem0,memory
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: falkordb>=1.6.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rank-bm25>=0.2.0
Provides-Extra: dev
Requires-Dist: mem0ai; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

[![license](https://img.shields.io/github/license/falkordb/mem0-falkordb.svg)](https://github.com/falkordb/mem0-falkordb)
[![PyPI version](https://badge.fury.io/py/mem0-falkordb.svg)](https://badge.fury.io/py/mem0-falkordb)
[![Codecov](https://codecov.io/gh/falkordb/mem0-falkordb/branch/main/graph/badge.svg)](https://codecov.io/gh/falkordb/mem0-falkordb)
[![Forum](https://img.shields.io/badge/Forum-falkordb-blue)](https://github.com/orgs/FalkorDB/discussions)
[![Discord](https://img.shields.io/discord/1146782921294884966?style=flat-square)](https://discord.gg/ErBEqN9E)

# mem0-falkordb

[![Try Free](https://img.shields.io/badge/Try%20Free-FalkorDB%20Cloud-FF8101?labelColor=FDE900&style=for-the-badge&link=https://app.falkordb.cloud)](https://app.falkordb.cloud)

FalkorDB graph store plugin for [Mem0](https://github.com/mem0ai/mem0). Adds FalkorDB as a graph memory backend **without modifying any Mem0 source code**.

## Installation

```bash
pip install mem0-falkordb
```

You also need Mem0 installed separately:

```bash
pip install mem0ai
```

## Quick Start

```python
from mem0_falkordb import register
register()

from mem0 import Memory

config = {
    "graph_store": {
        "provider": "falkordb",
        "config": {
            "host": "localhost",
            "port": 6379,
            "database": "mem0",
        },
    },
    # Add your LLM and embedder config as usual
    "llm": {
        "provider": "openai",
        "config": {"model": "gpt-4o-mini"},
    },
}

m = Memory.from_config(config)
m.add("I love pizza", user_id="alice")
results = m.search("what does alice like?", user_id="alice")
```

<img width="1827" height="936" alt="image" src="https://github.com/user-attachments/assets/857c1112-0688-4025-ace0-ac63f195a48a" />

## Demo

See the [`demo/`](demo/) directory for a comprehensive multi-user demonstration showcasing:
- **Graph-structured memory** — relationships between entities, not just flat facts
- **Per-user graph isolation** — each user gets their own FalkorDB graph
- **Context-aware retrieval** — semantic search with vector embeddings
- **Memory evolution** — updates and conflict resolution
- **Visual inspection** — see the actual graph structure

```bash
docker run --rm -p 6379:6379 falkordb/falkordb:latest
cd demo
uv sync
export OPENAI_API_KEY='your-key-here'
uv run python demo.py
```

See [demo/README.md](demo/README.md) for complete instructions.

## Configuration

| Parameter    | Type   | Default     | Description                                |
|-------------|--------|-------------|--------------------------------------------|
| `host`      | str    | `localhost` | FalkorDB server host                       |
| `port`      | int    | `6379`      | FalkorDB server port                       |
| `database`  | str    | `mem0`      | Graph name prefix (each user gets `{database}_{user_id}`) |
| `username`  | str    | `None`      | Authentication username (optional)         |
| `password`  | str    | `None`      | Authentication password (optional)         |
| `base_label`| bool   | `True`      | Use `__Entity__` base label                |

### Per-User Graph Isolation

Each user automatically gets their own isolated FalkorDB graph (e.g. `mem0_alice`, `mem0_bob`). This leverages FalkorDB's native multi-graph support and provides:

- **Natural data isolation** — no user_id filtering needed in Cypher queries
- **Simpler, faster queries** — no WHERE clauses on user_id
- **Easy cleanup** — `delete_all` simply drops the user's graph

## Running FalkorDB

Using Docker:

```bash
docker run --rm -p 6379:6379 falkordb/falkordb
```

## How It Works

This plugin uses Python's runtime patching to register FalkorDB into Mem0's existing factory system:

1. `GraphStoreFactory.provider_to_class` gets a new `"falkordb"` entry
2. `GraphStoreConfig` is patched to accept `FalkorDBConfig`
3. A `MemoryGraph` class translates Mem0's graph operations to FalkorDB-compatible Cypher

### Key Cypher Translations

| Neo4j                                    | FalkorDB                                          |
|------------------------------------------|---------------------------------------------------|
| `elementId(n)`                           | `id(n)`                                           |
| `vector.similarity.cosine()`             | `db.idx.vector.queryNodes()` procedure            |
| `db.create.setNodeVectorProperty()`      | `SET n.embedding = vecf32($vec)`                  |
| `CALL { ... UNION ... }` subqueries      | Separate outgoing + incoming queries              |

## Development

```bash
git clone <repo>
cd mem0-falkordb
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
```

