pgmem docs

Installing pgmem is two steps: add the SDK to your project, and apply the schema once to your Postgres database. There's no service to run and no new datastore — pgmem is a Python library plus SQL that lives in the Postgres you already have.

Prerequisites

A PostgreSQL database with the pgvector and btree_gist extensions available. Managed Postgres (Supabase, Neon, RDS, Cloud SQL, Azure) ships both.
Python 3.11+.

Steps

Install the SDK

pgmem is published on PyPI. Add it with your package manager of choice:

uv add pgmem
# optional provider adapter:
uv add "pgmem[openai]"      # or pgmem[anthropic] / pgmem[ollama]

pip install pgmem
# optional provider adapter:
pip install "pgmem[openai]"      # or pgmem[anthropic] / pgmem[ollama]

poetry add pgmem
# optional provider adapter:
poetry add "pgmem[openai]"       # or pgmem[anthropic] / pgmem[ollama]

pgmem imports cleanly with no LLM SDK installed. The extras are only needed if you want a built-in provider adapter — otherwise implement the Embedder / LLMClient protocols yourself and pass them to PgMem.

Enable the Postgres extensions

pgmem needs pgvector (vector search) and btree_gist (tenant-scoped range indexes). Enable them once on your database:

CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS btree_gist;

On managed Postgres both are whitelisted. If your database role can't create extensions, have an admin run these two lines once.

Apply the pgmem schema

The schema ships as plain, idempotent SQL in the repo (it is not bundled in the Python package). Fetch it and apply it once to your database:

git clone https://github.com/WebDeveloperBen/pgmem
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f pgmem/sql/migrations/install.sql

This creates everything under the pgmem schema namespace — tables, indexes, and functions. install.sql is safe to re-run and already includes the two CREATE EXTENSION lines from the previous step, so if your role can create extensions you can run it directly and skip step 2.

Verify

Check the schema is applied — this lists the versioned migrations on record:

psql "$DATABASE_URL" -c "SELECT version FROM pgmem.schema_migrations ORDER BY version;"

Then confirm the SDK connects (inside an async context):

from pgmem import PgMem

mem = await PgMem.create("postgresql://user:pass@host:5432/db")
# With no providers you already have the full session layer:
# turns, memory, compaction, and context.

You're ready to run the quickstart.

Gotchas

The embedding dimension is fixed at 1536 in the schema (vector(1536)). If you wire an embedder, it must produce 1536-dim vectors or PgMem.create fails. The session layer (turns, memory, compaction, context) needs no embedder or LLM at all — you only need providers for the semantic graph (Tier 4).

Managed Postgres: pgvector and btree_gist are whitelisted on the major providers; you don't need superuser, just a role that can CREATE EXTENSION (or an admin to run it once).
Self-hosted Postgres can instead install pgmem as a first-class extension (CREATE EXTENSION pgmem) using the packaged sql/extension/pgmem--*.sql. See SQL layer & schema.
Full-text search works out of the box on native Postgres; pgmem uses a BM25 backend automatically when one is available.

Quickstart — your first session
SQL layer & schema — what the schema installs
Protocols — bringing your own embedder / LLM
Deployment — applying the schema in production

Installation