Changing Honcho Embedding Dimensions: From 1536 to 1024

The Problem

Honcho stores embeddings in a pgvector column. On first startup, the Alembic migration pins the embedding column to vector(1536) — Honcho’s default.

My .env had:

EMBEDDING_VECTOR_DIMENSIONS=1024
EMBEDDING_MODEL_CONFIG__MODEL=bge-m3
EMBEDDING_MODEL_CONFIG__TRANSPORT=openai
EMBEDDING_MODEL_CONFIG__DIMENSIONS_MODE=always

bge-m3 outputs 1024-dimensional vectors, but the database column was already vector(1536). The startup validator detected a mismatch between schema and config, refused to start, and the API container logs reported a dimension mismatch.

Why Changing .env Alone Doesn’t Work

EMBEDDING_VECTOR_DIMENSIONS is treated as immutable in Honcho. The dimension is pinned by the Alembic migration on first run — changing .env afterwards doesn’t trigger an ALTER COLUMN. The official docs cover this in the Bootstrapping non-default dimensions section.

To change the dimension, you need the scripts/configure_embeddings.py script inside the container, and the table must be empty. If there’s existing data, the only official option is to rebuild a new deployment and migrate data — there’s no in-place re-embedding path.

Deployment Structure

My Honcho is deployed with Podman + Quadlet in ~/pod/honcho:

The database container uses pgvector/pgvector:pg15 with the pgvector extension pre-installed. init.sql contains a single line: CREATE EXTENSION IF NOT EXISTS vector;.

Fix Steps

1. Start a Temporary Container

The API container can’t start due to validation failure, but the database and Redis are fine. You need a container with access to the database network to run the script, with the entrypoint overridden so it doesn’t start Honcho:

systemctl --user start honcho-database.service honcho-redis.service

podman run --rm -d --name honcho-bootstrap \
  --pod systemd-honcho \
  -v /home/nite/pod/honcho/.env:/app/.env:ro \
  -e DB_CONNECTION_URI=postgresql+psycopg://postgres:[email protected]:5432/postgres \
  --entrypoint sh \
  ghcr.io/plastic-labs/honcho:latest \
  -c "sleep 300"

--pod systemd-honcho is the Quadlet-generated pod name (prefixed with systemd-). Using --entrypoint sh -c "sleep 300" keeps the container alive without running Honcho’s startup process.

2. Preview the Change

podman exec honcho-bootstrap /app/.venv/bin/python scripts/configure_embeddings.py --dry-run

The dry-run outputs what it plans to do: DROP HNSW index → ALTER column to vector(1024) → rebuild HNSW index. Confirm everything looks right before proceeding.

3. Apply the Change

podman exec honcho-bootstrap /app/.venv/bin/python scripts/configure_embeddings.py --yes

The script completes in a single transaction. My table was empty, so a direct ALTER worked fine.

4. Clean Up and Start

podman rm -f honcho-bootstrap
systemctl --user start honcho-api.service honcho-deriver.service

Verify:

curl -s http://127.0.0.1:8001/health
# {"status":"ok"}