Changing the embedding model

01Understand where the size is set

Two settings in the config file ~/.nexusbrain/config.json decide the embedding size: embedding_model and embedding_dimensions. They can be overridden for one shell with the NEXUS_BRAIN_EMBEDDING_MODEL and NEXUS_BRAIN_EMBEDDING_DIMENSIONS environment variables.

When the brain is created, nexusbrain init sizes the content_chunks.embedding column as vector(N) using those settings. Changing the settings later does not resize the column. That is why a model change needs one of the procedures below.

You cannot change these two keys with nexusbrain config set. That command writes to the database, which the embed pipeline never reads for these keys, so it refuses and prints the correct recipe instead.

02Detect a mismatch and estimate the cost

1. 1

   Run the health check.

   Do not add --fast. That flag skips every database check, including the embedding checks.

   nexusbrain doctor

   Copy

   You should seeA list of checks, each marked [OK], [WARN] or [FAIL]. On a healthy brain, embedding_width_consistency reads Schema width (1536d) matches gateway embedding_dimensions with your own number.

2. 2

   Look for the width warning.

   A mismatch shows as [WARN] embedding_width_consistency: Schema width mismatch: content_chunks.embedding is vector(1536) but gateway resolved embedding_dimensions = 1280. followed by Embedding dimension mismatch detected. and a copyable recipe for your engine.

   If your provider key works, the embedding_provider check may also report DB dimension mismatch: column is vector(1536) but provider returns 1280-dim.

   You should seeYou know the current column size (the first number) and the size the new model needs (the second number).

3. 3

   Estimate the re-embedding cost before you change anything.

   Re-embedding sends every chunk in your brain to the new provider, so the cost grows with the size of your brain. For Postgres brains the brain itself warns that this can take hours and cost $1 to $100 in API calls.

   The migrate embeddings command has a planning mode that counts the work and prices it without changing anything. Use your new model and size.

   nexusbrain migrate embeddings --to openai:text-embedding-3-large --dim 1536 --dry-run

   Copy

   You should seeAn Embedding migration plan block with From:, To:, Chunks to re-embed: and Estimated cost:. If the model has no pricing entry, it says the estimate is unknown and asks you to check the provider pricing.

03Rebuild on the local engine with one command

The local engine stores vectors with pgvector compiled to WebAssembly, which cannot change a vector column type in place. The supported path is to move the old brain aside, create a new one at the new size, and import your brain repo again. nexusbrain reinit-pglite does all three.

1. 1

   Stop nexusbrain serve if it is running.

   Close the terminal running it, or stop the agent app that launched it.

   You should seeNo nexusbrain serve process is left running.

2. 2

   Run the reinit command with the new model and size.

   Each flag defaults to the value in ~/.nexusbrain/config.json when you leave it out. Environment variable overrides are ignored on purpose, so a temporary shell setting cannot change the rebuild target.

   nexusbrain reinit-pglite --embedding-model zeroentropyai:zembed-1 --embedding-dimensions 1280

   Copy

   You should seeA plan listing Active brain:, Backup destination:, New embedding model:, New dimensions: and Re-sync after init:, then the prompt Wipe and reinit? (y/N):.

3. 3

   Type y and press Enter.

   You should seeBacked up brain to followed by the backup path, the init output, Re-syncing brain repo..., and finally Reinit complete. To roll back: with an mv command.

4. 4

   Embed anything the sync left pending.

   nexusbrain embed --stale

   Copy

   You should seeThe command embeds the remaining chunks, or finds nothing left to do.

5. 5

   Confirm the fix.

   nexusbrain doctor

   Copy

   You should seeembedding_width_consistency is [OK] and the embeddings check shows your coverage.

04Rebuild on the local engine by hand

This is the same procedure as reinit-pglite, one step at a time. The doctor message prints these exact commands with your real brain path filled in.

1. 1

   Move the current brain aside as a backup.

   mv ~/.nexusbrain/brain.pglite ~/.nexusbrain/brain.pglite.bak

   Copy

   You should seeThe folder brain.pglite.bak exists and brain.pglite does not.

2. 2

   Create a new brain at the new size.

   nexusbrain init --pglite --embedding-model openai:text-embedding-3-large --embedding-dimensions 1536

   Copy

   You should seeInit finishes and creates a fresh brain.pglite.

3. 3

   Re-import your brain repo from disk.

   nexusbrain sync

   Copy

   You should seeA summary such as First sync complete. with the number of files imported.

4. 4

   Rebuild the embeddings.

   nexusbrain embed --stale

   Copy

   You should seeChunks are embedded with the new model. nexusbrain doctor then shows the width check as [OK].

05Rebuild on Postgres

Postgres can change the column in place, so your pages stay and only the vectors are rebuilt. nexusbrain reinit-pglite refuses to run here, because wiping would delete the whole brain.

The simplest path is nexusbrain migrate embeddings. It checks the new provider with one live call before changing anything, rebuilds the column, updates the config, and re-embeds. If it is interrupted, run the same command again and it continues where it stopped.

1. 1

   Run the migration.

   nexusbrain migrate embeddings --to openai:text-embedding-3-large --dim 1536

   Copy

   You should seeThe migration plan, then the prompt to confirm. Without an interactive terminal, add --yes.

2. 2

   Confirm and wait for the re-embed.

   You should seeA line such as [migrate] schema rebuilt at 1536d, followed by embedding progress.

06Use the manual SQL recipe on Postgres

If you prefer to run the SQL yourself, this is the recipe the brain prints. Replace 1536 with your new size. The embeddings are set to NULL before the ALTER because pgvector refuses to convert existing vectors between sizes.

1. 1

   Run the column change in one transaction.

   BEGIN;
   DROP INDEX IF EXISTS idx_chunks_embedding;
   UPDATE content_chunks SET embedding = NULL, embedded_at = NULL;
   ALTER TABLE content_chunks ALTER COLUMN embedding TYPE vector(1536);
   CREATE INDEX IF NOT EXISTS idx_chunks_embedding
     ON content_chunks USING hnsw (embedding vector_cosine_ops);
   COMMIT;

   Copy

   You should seeThe transaction commits without errors.

2. 2

   Save the new model in the config.

   nexusbrain init --supabase --embedding-model openai:text-embedding-3-large --embedding-dimensions 1536

   Copy

   You should seeInit completes with the new embedding settings.

3. 3

   Rebuild the embeddings.

   nexusbrain embed --stale

   Copy

   You should seeChunks are embedded. nexusbrain doctor then shows embedding_width_consistency as [OK].

07Troubleshooting