# mem0server
A lightweight FastAPI wrapper around [mem0](https://github.com/mem0ai/mem0) providing persistent memory over a REST API, with local reranking support.
## Architecture
| Component | Provider | Address |
|-----------|----------|---------|
| LLM | Groq (`llama-3.1-8b-instant`) | cloud |
| Vector store | Chroma | `192.168.0.200:8001` |
| Embedder | Ollama (`nomic-embed-text`) | `192.168.0.200:11434` |
| Reranker | local REST server | `192.168.0.200:5200` |
## Setup
```bash
python -m venv mem0env
source mem0env/bin/activate
pip install fastapi uvicorn mem0 httpx
```
## Environment variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `GROQ_API_KEY` | ✅ yes | — | Groq API key |
| `RERANKER_URL` | no | `http://192.168.0.200:5200/rerank` | Local reranker endpoint |
```bash
export GROQ_API_KEY=your_key_here
# optional override:
export RERANKER_URL=http://localhost:5200/rerank
```
## Running
```bash
uvicorn mem0server:app --host 0.0.0.0 --port 8420
```

## Docker

### Build
```bash
docker build -t mem0server .
```

### Run

**Option A — pass the API key directly:**
```bash
docker run -p 8420:8420 -e GROQ_API_KEY=your_key_here mem0server
```

**Option B — use your `.env` file:**
```bash
docker run -p 8420:8420 --env-file .env mem0server
```

**Option C — override the reranker URL as well:**
```bash
docker run -p 8420:8420 \
  --env-file .env \
  -e RERANKER_URL=http://192.168.0.200:5200/rerank \
  mem0server
```

> ⚠️ Never bake your `.env` into the image. Always pass secrets at runtime via `--env-file` or `-e`.

## API
### `GET /health`
Returns server status and configured reranker URL.
```json
{ "status": "ok", "reranker_url": "http://192.168.0.200:5200/rerank" }
```
---
### `POST /memories`
Add a memory for a user.
```json
{ "text": "The user prefers dark mode.", "userId": "alice" }
```
---
### `POST /memories/search`
Search memories with reranking. Fetches `limit * 3` candidates from mem0, then reranks them locally.
```json
{ "query": "UI preferences", "userId": "alice", "limit": 5 }
```
Returns results with an added `rerank_score` field.
---
### `POST /memories/recent`
Return the most recently created memories for a user.
```json
{ "userId": "alice", "limit": 5 }
```
---
### `DELETE /memories`
Delete memories by filter.
```json
{ "filter": { "user_id": "alice" } }
```
## Reranker contract
The server expects a reranker at `RERANKER_URL` accepting:
```json
{
  "query": "...",
  "documents": ["doc1", "doc2", "..."],
  "top_k": 5
}
```
And returning:
```json
{
  "results": [
    { "text": "doc1", "score": 0.99 },
    { "text": "doc2", "score": 0.87 }
  ]
}
```
If the reranker is unreachable, search falls back gracefully to the raw mem0 results.