DURING MY SELF HOSTING JOURNEY of basic-memory I, or lets be honest - Claude Code came accross this:

Issue draft 1 — Documentation improvement

Template to choose: Documentation improvement

Suggested title:
docker-compose-postgres.yml and Postgres docs reference plain postgres:17 — semantic-search setup silently fails without pgvector

NOTE: I have not seen Basic Memory's actual Documentation-improvement template — the structure below uses generic Description / Location / Suggested change / Acceptance headings. If the issue form prompts for different fields, fill those in and treat the prose below as the body.

Issue body (copy-paste below this line)

Description

The official docker-compose-postgres.yml on main uses image: postgres:17, and the Postgres-related reference docs do not mention that the Postgres backend requires the pgvector extension. A user who follows the documented setup ends up with a Postgres instance that cannot run CREATE EXTENSION vector, and the semantic-search code path added in #550 (v0.19.0) silently fails or degrades on first start.

Where in the docs / repo

• docker-compose-postgres.yml — services.postgres.image: postgres:17 (no pgvector).
• content/8.reference/6.configuration.md and content/8.reference/7.docker.md describe database_backend: postgres, semantic_embedding_model, etc. but never tell the user that the Postgres image itself must ship pgvector.

From a fresh reader's perspective, "use the docker-compose-postgres.yml" is presented as the supported path, so the gap is not obvious until first start.

Why this happens

The original Postgres backend PR (#439) predates the semantic-search PR (#550, v0.19.0). The compose file was correct when written; it just was not updated when pgvector became a hard dependency for the Postgres path.

Suggested change

Either of:

(a) Swap the base image in docker-compose-postgres.yml:

services:
  postgres:
    image: pgvector/pgvector:pg17    # bundles the pgvector extension

(b) Keep postgres:17 but add a tiny custom Dockerfile alongside the compose file that does apt-get install postgresql-17-pgvector and use build: instead of image:.

Either way, also add a one-paragraph note to the Postgres backend section of 8.reference/6.configuration.md (and/or 8.reference/7.docker.md) along the lines of:

"The Postgres backend requires the pgvector extension. The provided docker-compose-postgres.yml uses an image that bundles it. If you point Basic Memory at an existing Postgres instance, ensure pgvector is installed (CREATE EXTENSION IF NOT EXISTS vector;) before running the first migration."

Acceptance check

After the change, on a fresh stack, this should succeed without manual intervention:

\c basic_memory
SELECT extname, extversion FROM pg_extension WHERE extname = 'vector';

and the Alembic migration that creates the embedding table should not error.

Environment

• basic-memory: 0.20.3
• Path observed: Docker Compose (docker-compose-postgres.yml)
• Self-hosted (not Basic Memory Cloud)