# Memory Migrate

Source: https://flow-next.dev/skills/memory-migrate/

Lift legacy flat memory files into the categorized YAML schema.

`/flow-next:memory-migrate` converts pre-fn-30 flat memory files into the categorized schema that current flow-next expects.

Old flow-next stored memory as three flat markdown files at `.flow/memory/`: `pitfalls.md`, `conventions.md`, `decisions.md`. fn-30 introduced one-entry-per-file with track / category / module / tags / status frontmatter, but the flat files persisted and became invisible to `memory list`, `memory search`, and `/flow-next:audit`.

## When to use it

* The repo has `.flow/memory/pitfalls.md`, `conventions.md`, or `decisions.md` at the root.
* `/flow-next:audit` reported a non-zero “legacy entries skipped” count.
* Search and scout skills do not surface entries you remember writing.

If no legacy files exist, nothing happens - the skill exits cleanly.

## How it classifies

Each entry gets a mechanical default `(track, category)` from the source filename:

| Source           | Default track | Default category |
| ---------------- | ------------- | ---------------- |
| `pitfalls.md`    | `bug`         | `build-errors`   |
| `conventions.md` | `knowledge`   | `patterns`       |
| `decisions.md`   | `knowledge`   | `decisions`      |

The host agent overrides the default only when the entry body unambiguously points elsewhere. An entry titled “race condition in worker pool” inside `pitfalls.md` clearly warrants `bug/runtime-errors`, not the mechanical `bug/build-errors`.

## Invocation

| Mode                     | Behavior                                                                                                                                                            |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Interactive (default)    | Ask via blocking question when an entry’s content suggests overriding the mechanical default. Confirm cleanup before renaming originals.                            |
| Autofix (`mode:autofix`) | No user questions. Accept mechanical defaults except where the body unambiguously overrides them. Mark genuinely ambiguous entries as `needs-review` in the report. |

A scope hint after the mode token (e.g. `pitfalls.md`) narrows the migration to one legacy file.

## After migration

Originals stay in place by default until you confirm cleanup. The interactive mode offers a rename to `*.md.legacy` so the files remain readable but are clearly not the current source of truth. Autofix mode default-declines this and surfaces the suggestion as a recommendation.

`/flow-next:audit` will now find every entry. Run it after migration if the legacy files were old enough that some entries are likely stale.

## Where it stops

* Not a content rewrite. The migration preserves the original wording verbatim, only adding schema. Quality review is the audit’s job.
* Not destructive. Nothing is deleted automatically; cleanup is always a separate confirmation.

## Worked example

```plaintext
/flow-next:memory-migrate
```

```text
Legacy files found: pitfalls.md (7 entries), conventions.md (4), decisions.md (3)
Classifying... 12 mechanical defaults kept, 2 overridden by content
  "race condition in worker pool" -> bug/runtime-errors (was bug/build-errors)
Written: 14 categorized entries under .flow/memory/<track>/<category>/
Legacy files retired. memory list / search / audit now see everything.
```

One run, and entries invisible to `memory search` become first-class citizens of the current schema.

* Run it once per repo that predates fn-30 - the symptom is `/flow-next:audit` reporting legacy entries skipped, or remembered entries missing from search.
* The filename-based classification is a default, not a verdict; entries whose body clearly points elsewhere get re-routed.
* No legacy files means a clean no-op exit - it is always safe to run speculatively.

## Dynamic usage

Recipes that compose with memory-migrate in the [cookbook](https://flow-next.dev/guides/cookbook/):

* [Integration tricks](https://flow-next.dev/guides/cookbook/#integration-tricks) - migrated memory feeds the scouts that ground plans and reviews.
* [Evidence-first](https://flow-next.dev/guides/cookbook/#evidence-first) - categorized entries carry structured frontmatter your own tooling can query.

## Next step

```bash
/flow-next:audit
```