chore(brain): migrate legacy notes into wing/hall layout #22

New Issue

mathias · 2026-05-19T11:11:15Z

mathias commented

2026-05-19 11:11:15 +00:00

Context

hyperguild#1 introduced the wing/hall taxonomy and brain/wiki/<wing>/<hall>/ layout. New writes via brain_write(wing=..., hall=...) land there cleanly. The existing corpus is still in the legacy flat shape: brain/knowledge/, brain/wiki/concepts/, brain/wiki/entities/.

Migration is one-shot via scripts/migrate-brain-halls.sh.

Action

Take a backup of brain/ (rsync to a sibling dir or the laptop):

rsync -a /var/lib/supervisor/brain/ /var/lib/supervisor/brain.bak-$(date -u +%Y%m%d)/

Dry-run on koala:

kubectl exec -n supervisor deploy/ingestion -- \
  /app/scripts/migrate-brain-halls.sh /app/brain

…or run against a local Syncthing copy first if available.

Inspect the proposed move: lines, sanity-check wing/hall mapping.
Apply with --commit.
Backfill embeddings (separate issue) so the new paths are indexed.
Verify Obsidian vault still opens cleanly if you mount brain/ as a vault.

Acceptance criteria

Backup of brain/ exists outside the live path
migrate-brain-halls.sh --commit runs with zero skip (target exists) warnings (or each is justified)
brain/wiki/concepts/ and brain/wiki/entities/ are empty afterwards
brain_index regenerates _index.md for every wing
Hybrid retrieval (post-backfill) returns sane results for a few known queries

Risks

The migrate script uses git mv when the directory is a git checkout, else mv. The live brain/ on koala is NOT a git repo — operations are filesystem moves. No rollback short of the backup.

Out of scope

Cleaning up the slug-vs-title humanisation edge cases in BuildWingIndex. Track separately if they bite.

## Context hyperguild#1 introduced the wing/hall taxonomy and `brain/wiki/<wing>/<hall>/` layout. New writes via `brain_write(wing=..., hall=...)` land there cleanly. The existing corpus is still in the legacy flat shape: `brain/knowledge/`, `brain/wiki/concepts/`, `brain/wiki/entities/`. Migration is one-shot via `scripts/migrate-brain-halls.sh`. ## Action 1. Take a backup of `brain/` (rsync to a sibling dir or the laptop): ```bash rsync -a /var/lib/supervisor/brain/ /var/lib/supervisor/brain.bak-$(date -u +%Y%m%d)/ ``` 2. Dry-run on koala: ```bash kubectl exec -n supervisor deploy/ingestion -- \ /app/scripts/migrate-brain-halls.sh /app/brain ``` …or run against a local Syncthing copy first if available. 3. Inspect the proposed `move:` lines, sanity-check wing/hall mapping. 4. Apply with `--commit`. 5. Backfill embeddings (separate issue) so the new paths are indexed. 6. Verify Obsidian vault still opens cleanly if you mount `brain/` as a vault. ## Acceptance criteria - [ ] Backup of `brain/` exists outside the live path - [ ] `migrate-brain-halls.sh --commit` runs with zero `skip (target exists)` warnings (or each is justified) - [ ] `brain/wiki/concepts/` and `brain/wiki/entities/` are empty afterwards - [ ] `brain_index` regenerates `_index.md` for every wing - [ ] Hybrid retrieval (post-backfill) returns sane results for a few known queries ## Risks The migrate script uses `git mv` when the directory is a git checkout, else `mv`. The live `brain/` on koala is NOT a git repo — operations are filesystem moves. No rollback short of the backup. ## Out of scope Cleaning up the slug-vs-title humanisation edge cases in `BuildWingIndex`. Track separately if they bite.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: mathias/hyperguild#22