Spaces:
Paused
Paused
| 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) | |