## Overview

The self-hosted Mem0 server has upgraded its PostgreSQL Docker image:

|  | Before | After |
| --- | --- | --- |
| Docker image | `ankane/pgvector:v0.5.1` | `pgvector/pgvector:pg17` |
| PostgreSQL | 15 | 17 |
| pgvector | 0.5.1 | 0.8.0 |
| Credentials | Hardcoded `postgres` / `postgres` | Set via `POSTGRES_USER` / `POSTGRES_PASSWORD` env vars |

The `ankane/pgvector` image is **archived and no longer maintained**. The new `pgvector/pgvector` image is the official distribution maintained by the pgvector project.

**Should you migrate?**

- You are running the Mem0 server via `docker-compose.yaml` in the `server/` directory.
- You want to stay on a maintained, actively-patched PostgreSQL + pgvector image.
- You want pgvector 0.8.0 features (improved HNSW performance, parallel index builds).

## Fresh Installs

No migration is needed. Copy the example env file, set your password, and start the stack:

```
cd server
cp .env.example .env
# Edit .env: set POSTGRES_PASSWORD (required) and OPENAI_API_KEY at minimum
make up
```

## Migrating an Existing Install

PostgreSQL 17 cannot read data files created by PostgreSQL 15 directly. You need to export your data from the old container and import it into the new one.

### 1. Back Up Your Data

With the **old** stack still running:

```
cd server
docker compose exec -T postgres pg_dumpall -U postgres > mem0_backup.sql
```

Verify the dump is non-empty:

```
ls -lh mem0_backup.sql
```

Do not skip this step. The next step permanently deletes your Postgres data volume.

### 2. Stop the Old Stack and Remove the Volume

```
docker compose down
docker compose down -v
```

### 3. Update Your `.env`

Postgres credentials are no longer hardcoded in `docker-compose.yaml`. Add them to your `.env`:

```
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=postgres
POSTGRES_USER=postgres
POSTGRES_PASSWORD=<your-password>    # required: compose will refuse to start without it
POSTGRES_COLLECTION_NAME=memories
```

`POSTGRES_PASSWORD` is **required**: `docker compose up` will refuse to start without it. If you previously relied on the hardcoded default, set `POSTGRES_PASSWORD=postgres`.

### 4. Start Only Postgres

Start **only** the Postgres container first: do **not** start the mem0 API yet.
The API runs `alembic upgrade head` on startup, which creates empty tables that would conflict with the restore.

```
docker compose up -d postgres
```

Wait for Postgres to become healthy:

```
docker compose exec -T postgres pg_isready -q && echo "ready" || echo "not ready"
```

### 5. Restore Your Data

```
docker compose exec -T postgres psql -U postgres < mem0_backup.sql
```

You may see notices like `role "postgres" already exists`: these are safe to ignore.

You must restore **before** starting the mem0 API container. The API runs database migrations on startup which create empty tables: restoring after that would fail with duplicate-key errors and lose your API keys and settings.

### 6. Start the API

Now start the mem0 API container. Alembic will detect the existing tables and only apply any new migrations:

```
docker compose up -d mem0
```

### 7. Verify

```
# Check service health
cd server && make health

# Confirm memories are accessible
curl -s http://localhost:8888/memories?user_id=<your-user-id> \
  -H "X-API-Key: <your-api-key>"
```

## Rollback

If something goes wrong, revert the image tag in `docker-compose.yaml`:

```
postgres:
    image: ankane/pgvector:v0.5.1
```

Then destroy the new volume, start the old image, and restore from your backup:

```
docker compose down -v
docker compose up -d --build
docker compose exec -T postgres psql -U postgres < mem0_backup.sql
```