# v0.3 to v0.4 migration guide

## What changed

Dense embedding vectors are no longer stored inline on `Node` bytes.
They now live in a per-commit Prolly sidecar tree (`Commit.embeddings`,
keyed by `NodeCid`). This makes `NodeCid` byte-identical across machines
regardless of embedder thread counts or floating-point reduction order.

## Pre-upgrade backup

```sh
cp -r .mnem .mnem.bak
```

## What happens to v0.3 data when opened by v0.4

v0.4 reads old repos transparently. The DAG-CBOR `embed` map that was
inline on `Node` in v0.3 is absorbed into `node.extra["embed"]` by the
forward-compat flatten decoder. `NodeCid` is unchanged - the bytes
round-trip identically.

Nodes are fully queryable (graph traversal, prop lookups, text search).
They just have no entry in the embedding sidecar yet, so
nearest-neighbour retrieval will not return them until you run one of
the two paths below.

## Path 1 - re-derive from text (default, needs embedder)

```sh
mnem config set embed.provider ollama
mnem config set embed.model nomic-embed-text
mnem reindex
```

This calls the configured embedder for each node and writes fresh vectors
into the sidecar. Safe to run multiple times (idempotent unless `--force`
is passed).

## Path 2 - lift existing vectors without an embedder

```sh
mnem reindex --lift-legacy-extra
```

Reads the raw `Embedding` bytes from `node.extra["embed"]` and promotes
them directly into the sidecar without any network or model call. Works
offline and preserves the original vectors exactly. Preferred for
operators who do not have the original embedder available.

`--dry-run` is supported: counts how many nodes have `extra["embed"]`
without touching storage.

## Verifying NodeCid stability after reindex

Pick any node UUID and confirm its CID matches before and after:

```sh
mnem get <uuid>         # note "node_cid: <cid>"
mnem reindex --lift-legacy-extra
mnem get <uuid>         # must show the same node_cid
```

Alternatively, `mnem cat-file <node_cid>` should decode successfully
and return the same bytes as before.

## Note: nodes without a vector after upgrade

If neither `mnem reindex` nor `mnem reindex --lift-legacy-extra` is
run (or `--lift-legacy-extra` is skipped and the embedder is
unavailable), nodes are fully accessible via graph and prop queries but
will not appear in `mnem retrieve --text` nearest-neighbour results
until reindexed.
