Metadata-Version: 2.4
Name: mnemo-hybmem
Version: 0.1.0
Summary: Mnemo backend
Author: Ojas
Author-email: ojasdhargave@gmail.com
Requires-Python: >=3.10,<4.0
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
Requires-Dist: fastapi (>=0.111.0,<0.112.0)
Requires-Dist: litellm (>=1.40.0,<2.0.0)
Requires-Dist: neo4j (>=5.21.0,<6.0.0)
Requires-Dist: pydantic (>=2.7.4,<3.0.0)
Requires-Dist: pydantic-settings (>=2.3.4,<3.0.0)
Requires-Dist: qdrant-client (>=1.9.1,<2.0.0)
Requires-Dist: sentence-transformers (>=3.0.1,<4.0.0)
Requires-Dist: sqlmodel (>=0.0.19,<0.0.20)
Requires-Dist: uvicorn (>=0.30.1,<0.31.0)
Description-Content-Type: text/markdown

# 🏛️ Mnemo Backend: The Hybrid Memory Layer

**Mnemo** is a cutting-edge **Python package** and **REST server** that gives Large Language Models (LLMs) a long-term memory. Unlike traditional vector databases that store isolated chunks of text, Mnemo builds a **dynamic knowledge graph** where concepts are connected by explicit relationships.

This allows LLMs to answer complex relational questions (e.g., "My friend's brother works at the company I visited last year") by traversing the graph, rather than just searching for keywords.

## ✨ Key Features

- **Hybrid Storage**:
  - 🧠 **Graph (Neo4j)**: Stores relationships (Subject-Predicate-Object) and explicit connections.
  - 🗄️ **Vector (Qdrant)**: Stores embeddings for fast semantic similarity search.
  - 📋 **Metadata (SQLite/Postgres)**: Tracks access frequency, importance, and decay.

- **LLM-Powered Extraction**:
  - Uses **LiteLLM** to route requests to the best available LLM (Gemini, OpenAI, Claude).
  - Automatically extracts entities, relations, and importance scores from raw text.

- **Intelligent Retrieval**:
  - **Retrieval Planner**: Determines whether a query needs Vector Search, Graph Traversal, or a Hybrid approach.
  - **Dynamic Ranking**: Combines vector similarity, graph distance, time decay, and access frequency for the perfect answer.

- **Developer Friendly**:
  - **Python SDK**: Lightweight client for both local in-process use and remote server calls.
  - **FastAPI Server**: Exposes a robust REST API for easy integration into larger applications.
  - **Dockerized**: Pre-built environments for Qdrant, Neo4j, and the backend.

## 🚀 Quick Start

### Prerequisites
- Python 3.10+
- Docker Desktop

### Option 1: Local Development (In-Process)

This runs everything inside your Python environment without needing a separate server.

1.  **Install Dependencies**:
    ```bash
    cd E:\Mnemo\backend
    poetry install
    ```

2.  **Set Environment Variables**:
    Create a `.env` file in the `backend` directory:
    ```env
    QDRANT_HOST=localhost
    QDRANT_PORT=6333
    NEO4J_URI=bolt://localhost:7687
    NEO4J_USER=neo4j
    NEO4J_PASSWORD=your_password_here
    LLM_PROVIDER=openai
    LLM_API_KEY=your_key_here
    ```

3.  **Run the Demo Script**:
    ```bash
    python example_manual.py
    ```
    This will:
    - Start Neo4j and Qdrant containers (first time only).
    - Remember a sample memory.
    - Search for it.
    - Delete it.

### Option 2: Server Mode (Remote)

This runs the backend as a standalone service.

1.  **Install Dependencies**:
    ```bash
    cd E:\Mnemo\backend
    poetry install
    ```

2.  **Start the Server**:
    ```bash
    uvicorn mnemo.api.main:app --reload
    ```

3.  **Use the Remote SDK**:
    ```python
    from mnemo import Mnemo

    # Point SDK to the running FastAPI server
    sdk = Mnemo(mode="remote", api_url="http://127.0.0.1:8000")

    # Remember text
    sdk.remember(user_id="user_abc", text="I like coding in Python.")

    # Search
    results = sdk.search(user_id="user_abc", query="What language do I like?")
    ```

## 🗄️ Database Setup

The project includes `docker-compose.yml` to easily spin up the necessary infrastructure.

```bash
cd E:\Mnemo\backend
docker compose up -d
```

This will start:
- **Neo4j**: Port `7474` (Browser), `7687` (Bolt)
- **Qdrant**: Port `6333` (gRPC), `6334` (REST)

## 📁 Project Structure

```
backend/
├── mnemo/
│   ├── core/           # Core logic (config, database, vector, graph, AI)
│   ├── api/            # FastAPI endpoints
│   └── main.py         # Entry point & CLI
├── .env                # Environment variables
├── docker-compose.yml  # Docker configuration
└── pyproject.toml      # Dependencies
```

## 📋 SDK Usage

### Remember
```python
from mnemo import Mnemo

sdk = Mnemo(mode="local")  # or "remote"

# Extract entities, relations, and importance automatically
result = sdk.remember(
    user_id="user_123",
    text="Ojas studies Artificial Intelligence at IIIT Vadodara."
)

# Result includes extracted entities and relationships
print(result['extracted'])
```

### Search
```python
# Uses LLM to analyze query intent and performs hybrid search
results = sdk.search(user_id="user_123", query="Where does Ojas study AI?")

# Results are ranked by relevance (vector similarity + graph distance + decay)
print(results)
```

### Update
Modify existing memories by providing the `memory_id`.

### Delete / Forget
```python
# Delete a specific memory
sdk.forget(memory_id="abc-123")

# Delete all memories for a user
sdk.forget_user(user_id="user_123")
```

## 🛠️ Development

### Adding New LLMs
To add a new LLM provider (e.g., Hugging Face Inference Endpoint):

1.  Update `mnemo/core/config.py` to include the new provider in `LLMProvider` enum.
2.  Update `mnemo/core/config.py` to include the new API key/URL in `Settings`.
3.  (Optional) Update `mnemo/core/extractor.py` to handle provider-specific prompt formatting or parameters if needed.

### Adding New Vector Stores
To add a new vector database (e.g., Weaviate, Pinecone):

1.  Update `mnemo/core/config.py` to include the new provider in `VectorProvider` enum.
2.  Update `mnemo/core/config.py` to include the new connection settings in `Settings`.
3.  Update `mnemo/core/vector.py` to include a new client class and methods for the new provider.

## 🧪 Testing

```bash
# Run tests (FastAPI must be running in Docker)
poetry run pytest
```

## 🌐 Architecture

```
User SDK <---> FastAPI Server <---> Hybrid Memory Layer
                                    |
                      +-------------+-------------+
                      |             |             |
                   Qdrant         Neo4j      SQLite/Postgres
                (Vector)       (Graph)     (Metadata)
```




