mathias/hyperguild
1
0
Fork 0
Code Issues 30 Pull Requests 3 Actions Packages Projects Releases Wiki Activity

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

New Issue
Closed
opened 2026-05-19 11:11:15 +00:00 by mathias · 1 comment
mathias commented 2026-05-19 11:11:15 +00:00
Owner
Copy Link
Copy Source

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): 
    rsync -a /var/lib/supervisor/brain/ /var/lib/supervisor/brain.bak-$(date -u +%Y%m%d)/
  2. 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.
  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.

## 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.
mathias commented 2026-08-19 18:21:01 +00:00
Author
Owner
Copy Link
Copy Source

Verified live against mathias/brain: wiki/concepts/ (20 files) and wiki/entities/ (34 files) are not migration debris — they're active, currently-written wings with their own _index.md, containing content created/updated as recently as this week (wiki/entities/pi.md, wiki/entities/ornith.md, etc.). The taxonomy evolved since this issue was filed (2026-05-19): concepts/entities are legitimate permanent wings in the current wing/hall schema, not a flat legacy shape waiting to be moved elsewhere. This issue's acceptance criterion ("wiki/concepts/ and wiki/entities/ are empty afterwards") is now factually wrong — running that migration today would destroy live content, not clean up debris. Closing as superseded by how the schema actually evolved. Sprint cleanup pass, 2026-08-19.

Verified live against `mathias/brain`: `wiki/concepts/` (20 files) and `wiki/entities/` (34 files) are not migration debris — they're active, currently-written wings with their own `_index.md`, containing content created/updated as recently as this week (`wiki/entities/pi.md`, `wiki/entities/ornith.md`, etc.). The taxonomy evolved since this issue was filed (2026-05-19): `concepts`/`entities` are legitimate permanent wings in the current wing/hall schema, not a flat legacy shape waiting to be moved elsewhere. This issue's acceptance criterion ("wiki/concepts/ and wiki/entities/ are empty afterwards") is now factually wrong — running that migration today would destroy live content, not clean up debris. Closing as superseded by how the schema actually evolved. Sprint cleanup pass, 2026-08-19.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
agent/ready
Meets the agent-ready contract; authorizes unattended execution
 blocked/client
Waiting on the client
 blocked/supplier
Waiting on a supplier
 blocked/upstream
Waiting on an upstream project or vendor
 risk/high
Irreversible, security-relevant, or control plane
 risk/low
Reversible, local, test-covered
 risk/medium
Touches shared state, deploys or data
 size/l
Too big - split it
 size/m
Under two days
 size/s
Under half a day
 size/xs
Under an hour
 status:dispatch
status:dispatched
status:review
status:reviewing
type/chore
Maintenance, no behaviour change
 type/decision
Human decision required; never agent/ready
 type/docs
Documentation only
 type/feat
New capability
 type/fix
Corrects broken behaviour
 type/ops
Infrastructure, deploy, runtime
 type/research
Investigate; output is a finding, not code
 type/test
Test coverage only
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
renovate-bot mathias
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mathias/hyperguild#22