diff --git a/docs/memory.md b/docs/memory.md
index c58461a..26fccd0 100644
--- a/docs/memory.md
+++ b/docs/memory.md
@@ -2,9 +2,39 @@
 
 Long-term user memory: facts extracted from conversations, stored in SQLite, injected into every session.
 
+## PostgreSQL + pgvector (semantic search)
+
+When `DATABASE_URL` is set, the memory system uses **PostgreSQL with pgvector** for semantic search via embeddings.
+
+| Feature | SQLite | PostgreSQL |
+|---|---|---|
+| Storage | File-based | Server |
+| Semantic search | No | Yes (cosine distance on `vector(768)`) |
+| Embeddings | None | Generated via Ollama (`nomic-embed-text:latest`) |
+| Metadata | `category, key, value` | `+ source, confidence, expires_at, source_context` |
+
+---
+
+## Schema migration
+
+When upgrading the memory system to a new schema (e.g. adding pgvector columns), run:
+
+```bash
+.venv/bin/python navi/memory/migrate_pgvector.py
+```
+
+This script:
+1. Verifies the `vector` extension is installed in PostgreSQL
+2. Adds missing columns: `embedding`, `source`, `confidence`, `expires_at`, `last_verified_at`, `source_context`
+3. Creates indexes: `hnsw(embedding)`, `expires`, `source+category`
+
+Safe to run multiple times — all operations use `IF NOT EXISTS`.
+
+---
+
 ## Storage (`navi/memory/store.py`)
 
-Three tables in `navi.db`:
+Three tables in the database:
 
 | Table | Purpose |
 |---|---|
@@ -12,7 +42,7 @@
 | `memory_summary` | Single-row narrative summary generated from all facts |
 | `session_memory_state` | Tracks which sessions have been processed (by `extracted_at`) |
 
-`MemoryStore` is initialized synchronously (creates tables), all operations are async via aiosqlite.
+`MemoryStore` is initialized synchronously (creates tables), all operations are async via asyncpg (PostgreSQL) or aiosqlite (SQLite fallback).
 
 ### Key operations