README.md

metadata

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

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

2. Build and Run

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

docker compose logs -f mem0

Access Container

docker compose exec mem0 bash

Run Migrations Manually

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)