ContextQMD
Back to Mem0

Server: Upgrading the pgvector Docker Image

docs/migration/server-pgvector-upgrade.mdx

2.0.53.9 KB
Original Source

Overview

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

BeforeAfter
Docker imageankane/pgvector:v0.5.1pgvector/pgvector:pg17
PostgreSQL1517
pgvector0.5.10.8.0
CredentialsHardcoded postgres / postgresSet via POSTGRES_USER / POSTGRES_PASSWORD env vars
<Warning> The `ankane/pgvector` image is **archived and no longer maintained**. The new `pgvector/pgvector` image is the official distribution maintained by the pgvector project. </Warning> <Info> **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). </Info>

Fresh Installs

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

bash
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:

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

Verify the dump is non-empty:

bash
ls -lh mem0_backup.sql
<Warning> Do not skip this step. The next step permanently deletes your Postgres data volume. </Warning>

2. Stop the Old Stack and Remove the Volume

bash
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:

bash
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
<Info> `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`. </Info>

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.

bash
docker compose up -d postgres

Wait for Postgres to become healthy:

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

5. Restore Your Data

bash
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.

<Warning> 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. </Warning>

6. Start the API

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

bash
docker compose up -d mem0

7. Verify

bash
# 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:

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

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

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

Need Help?