---
title: Mem0
emoji: 📉
colorFrom: pink
colorTo: pink
sdk: docker
pinned: false
---

# mem0 Self-Hosted on HuggingFace Spaces

Single-container deployment of mem0 (API + Dashboard + PostgreSQL) for HuggingFace Spaces, following the patterns from `buzz` (single-container) and `hermes` (supervisord + nginx).

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    Single Container (Port 7860)             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  PostgreSQL │  │  mem0 API   │  │  mem0 Dashboard     │  │
│  │   (5432)    │  │  (8000)     │  │  (3000)             │  │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
│         │                │                      │            │
│         └────────────────┼──────────────────────┘            │
│                          ▼                                   │
│                   ┌─────────────┐                            │
│                   │    Nginx    │                            │
│                   │   (7860)    │                            │
│                   └─────────────┘                            │
│                          │                                   │
│                    ┌─────┴─────┐                             │
│                    │  Supervisord                              │
│                    └───────────┘                             │
└─────────────────────────────────────────────────────────────┘
```

## Quick Start

### 1. Clone and Setup

```bash
cd mem0
cp .env.example .env
# Edit .env with your values (required: POSTGRES_PASSWORD, OPENAI_API_KEY, JWT_SECRET)
```

### 2. Build and Run

```bash
docker compose build
docker compose up -d
```

### 3. Access

- **Dashboard**: http://localhost:7860
- **API Docs**: http://localhost:7860/docs
- **Health Check**: http://localhost:7860/health

## Required Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `POSTGRES_PASSWORD` | PostgreSQL password (generate: `openssl rand -base64 32`) | Yes |
| `OPENAI_API_KEY` | OpenAI API key for LLM/embeddings | Yes |
| `JWT_SECRET` | JWT signing secret (generate: `openssl rand -base64 48`) | Yes |
| `ADMIN_API_KEY` | Optional admin API key (generate: `openssl rand -base64 32`) | No |
| `AUTH_DISABLED` | Set to `true` for local dev only | No (default: false) |

## Features

- ✅ **Single container** - All services in one container (like buzz)
- ✅ **HF Spaces compatible** - Singleton guard prevents duplicate runners
- ✅ **UID 1000** - Works with HF FUSE idmapped mounts
- ✅ **Supervisord** - Manages PostgreSQL, API, Dashboard, Nginx
- ✅ **Nginx routing** - Single port 7860 routes to all services
- ✅ **Persistent storage** - PostgreSQL data persisted to `/data` volume
- ✅ **Auth enabled by default** - Secure by default (JWT + API keys)
- ✅ **Health checks** - Built-in health endpoints

## Nginx Routing

| Path | Proxies To |
|------|------------|
| `/` | Dashboard (Next.js on 3000) |
| `/api/` | mem0 API (FastAPI on 8000) |
| `/docs` | OpenAPI docs |
| `/redoc` | ReDoc docs |
| `/openapi.json` | OpenAPI spec |
| `/health` | Health check (direct) |

## Data Persistence

- **PostgreSQL**: `/data/pgdata` — cluster lives directly on the HF persistent volume (no sync/backup loop; FUSE-safe boot repair for empty dirs, `.git/` injection, and `pg_tblspc` symlink)
- **Request logs**: `/opt/data/history` (ephemeral; survives restarts only while the container lives)

## Development

### View Logs

```bash
docker compose logs -f mem0
```

### Access Container

```bash
docker compose exec mem0 bash
```

### Run Migrations Manually

```bash
docker compose exec mem0 gosu mem0 alembic upgrade head
```

## HF Spaces Deployment

1. Create new Space with **Docker** SDK
2. Push this repository
3. Set required secrets in Space settings:
   - `POSTGRES_PASSWORD`
   - `OPENAI_API_KEY`
   - `JWT_SECRET`
   - `ADMIN_API_KEY` (optional)
4. Space will auto-deploy on port 7860

## Troubleshooting

### PostgreSQL won't start
Check logs: `docker compose logs mem0 | grep postgresql`

### Dashboard shows "API connection failed"
Verify `NEXT_PUBLIC_API_URL=http://localhost:7860/api` in environment

### Auth errors
Ensure `JWT_SECRET` is set and `AUTH_DISABLED=false` (default)

### Port conflicts
Change port mapping in `docker-compose.yml`: `"7860:7860"` → `"YOUR_PORT:7860"`

## License

Apache 2.0 - Based on mem0 (https://github.com/mem0ai/mem0)