fix(server): harden self-hosted server — pgvector upgrade, admin auth, endpoint security

docs/docs.json

@@ -302,7 +302,8 @@
                     "group": "Migration",
                     "icon": "arrow-right",
                     "pages": [
-                      "migration/oss-v2-to-v3"
+                      "migration/oss-v2-to-v3",
+                      "migration/server-pgvector-upgrade"
                     ]
                   },
                   {

docs/llms.txt

@@ -228,6 +228,7 @@ If the user is on a pre-current major (Python < 2, TS < 3, or Platform `output_f
 - [OSS v2 to v3 Migration](https://docs.mem0.ai/migration/oss-v2-to-v3) [OSS]: Use when upgrading a self-hosted deployment across major versions.
 - [Platform v2 to v3 Migration](https://docs.mem0.ai/migration/platform-v2-to-v3) [Platform]: Use when upgrading a Platform integration across major versions.
 - [API Changes](https://docs.mem0.ai/migration/api-changes) [Both]: Use when the upgrade involves API surface changes.
+- [Server pgvector Image Upgrade](https://docs.mem0.ai/migration/server-pgvector-upgrade) [OSS]: Use when upgrading the self-hosted server Docker image from ankane/pgvector to pgvector/pgvector.
 - [Changelog](https://docs.mem0.ai/changelog/highlights) [Both]: Use when the user asks what shipped recently.
 
 ## Open Source

docs/migration/server-pgvector-upgrade.mdx

@@ -0,0 +1,158 @@
+---
+title: "Server: Upgrading the pgvector Docker Image"
+description: "Migrate your self-hosted Mem0 server from the archived ankane/pgvector image to the official pgvector/pgvector image."
+icon: "arrow-right"
+iconType: "solid"
+---
+
+## 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 |
+
+<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?
+
+- Join our [Discord community](https://mem0.ai/discord) for real-time support
+- Open an issue on [GitHub](https://github.com/mem0ai/mem0/issues)

server/.env.example

@@ -4,12 +4,13 @@ OPENAI_API_KEY=
 # ANTHROPIC_API_KEY=
 # GOOGLE_API_KEY=
 
-POSTGRES_HOST=
-POSTGRES_PORT=
-POSTGRES_DB=
-POSTGRES_USER=
+# Postgres — POSTGRES_PASSWORD is required; docker-compose will not start without it.
+POSTGRES_HOST=postgres
+POSTGRES_PORT=5432
+POSTGRES_DB=postgres
+POSTGRES_USER=postgres
 POSTGRES_PASSWORD=
-POSTGRES_COLLECTION_NAME=
+POSTGRES_COLLECTION_NAME=memories
 
 ADMIN_API_KEY=
 JWT_SECRET=

server/README.md

@@ -2,8 +2,24 @@
 
 Mem0 ships a self-hosted FastAPI server plus a local dashboard. It is secure by default, supports dashboard login and API keys, and exposes OpenAPI docs at `/docs`.
 
+> **Upgrading?** The Postgres image changed from the archived `ankane/pgvector:v0.5.1`
+> to the official `pgvector/pgvector:pg17`, and `POSTGRES_PASSWORD` is now a required
+> env var. If you have an existing install, see
+> [Migrating from ankane/pgvector to pgvector/pgvector](#migrating-from-ankanepgvector-to-pgvectorpgvector)
+> before running `docker compose up`.
+
 ## Quick Start
 
+### Prerequisites
+
+Copy the example env file and set a Postgres password (required):
+
+```bash
+cd server
+cp .env.example .env
+# Edit .env — at minimum set POSTGRES_PASSWORD and OPENAI_API_KEY
+```
+
 ### Agent-first
 
 Run one command; the terminal prints the admin email, password, and first API key.
@@ -121,6 +137,140 @@ The dashboard sets the following response headers on every path (see `server/das
 
 Together these prevent iframe embedding, sniffing of mislabelled MIME types, and cross-origin referrer leaks. Harden further behind your own reverse proxy if needed.
 
+## Migrating from `ankane/pgvector` to `pgvector/pgvector`
+
+The `ankane/pgvector` Docker image is archived and no longer maintained. This release
+replaces it with the official `pgvector/pgvector:pg17` image (PostgreSQL 17, pgvector 0.8.0).
+
+**What changed:**
+
+| | Before | After |
+|---|---|---|
+| Docker image | `ankane/pgvector:v0.5.1` | `pgvector/pgvector:pg17` |
+| PostgreSQL version | 15 | 17 |
+| pgvector version | 0.5.1 | 0.8.0 |
+| Credentials | Hardcoded `postgres`/`postgres` | Driven by `POSTGRES_USER` / `POSTGRES_PASSWORD` env vars |
+
+### Fresh installs (no existing data)
+
+No migration needed. Copy `.env.example` to `.env`, set `POSTGRES_PASSWORD`, and run:
+
+```bash
+cd server
+make up
+```
+
+### Existing installs (preserving data)
+
+PostgreSQL 17 cannot read data files written by PostgreSQL 15 directly.
+You must export your data first, then import it into the new container.
+
+**1. Export your data from the old container**
+
+With the old stack still running:
+
+```bash
+cd server
+
+# Dump all databases (mem0 memories + mem0_app auth/config data)
+docker compose exec -T postgres pg_dumpall -U postgres > mem0_backup.sql
+```
+
+Verify the dump file is non-empty:
+
+```bash
+ls -lh mem0_backup.sql
+```
+
+**2. Stop the old stack and remove the old volume**
+
+```bash
+# Stop containers
+docker compose down
+
+# Remove the old Postgres data volume
+docker compose down -v
+```
+
+> **Warning:** `docker compose down -v` deletes the `postgres_db` volume permanently.
+> Only run this after you have verified your backup.
+
+**3. Update your `.env`**
+
+The Postgres credentials are no longer hardcoded in `docker-compose.yaml`.
+Add them to your `.env` file (or verify they match your old setup):
+
+```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
+```
+
+If you previously relied on the hardcoded defaults (`postgres`/`postgres`), set
+`POSTGRES_PASSWORD=postgres` to keep the same credentials.
+
+**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 the Postgres healthcheck to pass:
+
+```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 harmless.
+
+> **Important:** 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:
+
+```bash
+docker compose up -d mem0
+```
+
+**7. Verify**
+
+```bash
+# Check the API is healthy
+make health
+
+# Confirm your memories are present
+curl -s http://localhost:8888/memories?user_id=<your-user-id> -H "X-API-Key: <your-api-key>"
+```
+
+### Rollback
+
+If you need to revert, restore the old image tag in `docker-compose.yaml`:
+
+```yaml
+postgres:
+    image: ankane/pgvector:v0.5.1
+```
+
+Then `docker compose down -v`, `docker compose up -d --build`, and restore from
+`mem0_backup.sql` into the old container the same way.
+
 ## Reference
 
 Additional product and API documentation lives at [docs.mem0.ai](https://docs.mem0.ai/open-source/overview).