# 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](https://honcho.dev/docs/v3/contributing/configuration#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`:

| File | Purpose |
|---|---|
| `honcho.pod` | Pod definition, publishes 8001:8000 |
| `honcho-database.container` | pgvector/pgvector:pg15 |
| `honcho-redis.container` | Redis cache |
| `honcho-api.container` | Honcho API service |
| `honcho-deriver.container` | Deriver service |
| `.env` | Environment variables |

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:

```bash
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:postgres@127.0.0.1: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

```bash
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

```bash
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

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

Verify:

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

---

> Author: Nite  
> URL: https://www.nite07.com/en/posts/honcho-embedding-dimensions/