goldbrain/migrate.md

Goldbrain Memory — Upgrade Guide (v0.2 → v0.7.1)

For: Bryan What this does: installs the new goldbrain-memory plugin and migrates your live Obsidian vault to the new structure — without losing any of your memory data. Time: ~15–20 minutes, done once. Endpoint: https://goldbrainapi.mpm.to (your Obsidian Local REST API, backend 192.168.86.15:27124). The API key is already baked into the plugin — there's nothing to configure.

---

The easiest way (recommended)

You don't have to run any of this by hand.

1. Back up your vault (see Step 0 — this one's on you, and it's required).

2. Install the new plugin (Step 1).

3. Open a Claude session with the new plugin active, hand it this file, and say:

   "Follow migrate.md and migrate my goldbrain vault. Stop after the dry-run and show me the plan before deleting anything."

Claude will run the bundled scripts, pause for your OK on the dry-run, finish the cleanup, and verify. The rest of this document is the exact procedure it (or you) will follow.

---

What changes — and why your data is safe

Only the structure changes. Every note that holds memory is preserved. The migration moves review notes into the journal and deletes only the old control docs (which carry no memory) and empty placeholder folders.

Old layout (v0.2)	New layout (v0.7.1)	What happens to your data
CLAUDE.md · BOOTSTRAP.md · STRUCTURE.md · index.md · spinup.md (in the vault)	Retired — all operating logic now ships inside the plugin	Deleted (these are control docs, not memory). Your Step 0 backup keeps a copy.
reviews/{weekly,monthly,quarterly,annual}/	journal/{weekly,monthly,quarterly,annual}/	Moved, intact. Monthly vault-health notes move to _agent/health/.
decisions/by-project/	Retired — the canonical record is decisions/by-date/; projects link to ADRs instead	by-date/ ADRs kept. Relocate any real by-project/ notes first (Step 3).
archive/	Retired — use projects/archived/ and _agent/skills/archived/	Relocate any real archived notes first (Step 3), then remove.
—	New: _agent/goldbrain-vault.md (version marker), _agent/locks/, _agent/health/	Added; nothing removed.
_agent/outputs/ · resources/source-material/	Kept (goldbrain-specific; the new plugin has routes for them)	Unchanged.
Everything else — operator-preferences.md, projects/, _agent/sessions/, journal/daily/, resources/people/, decisions/by-date/, etc.	Unchanged	Intact.

The new model in one line: the plugin is now the single source of truth. It no longer reads CLAUDE.md/BOOTSTRAP.md from your vault — the vault holds data only, and all the rules ship in the plugin.

---

Step 0 — Back up the vault (required, do not skip)

Before anything is deleted, make a full copy. Any one of these is fine:

• On the backend machine (192.168.86.15), copy the Obsidian vault folder somewhere safe, or
• If the vault is a git repo: git add -A && git commit -m "pre-v0.7.1-migration snapshot", or
• In Obsidian: export / duplicate the vault folder.

Keep the backup until you've finished Step 9 and confirmed everything reads correctly. If anything looks wrong, you restore this copy — that's the whole rollback plan.

---

Step 1 — Install the new plugin

1. Remove or disable the old goldbrain-memory v0.2 plugin.
2. Install goldbrain-memory-0.7.1.plugin (the file Jason gave you).
3. Confirm it loaded: ask Claude "load my goldbrain memory." It should quietly read your profile and recent context. (Reading memory at the start of a session is expected behavior.)

The old and new plugins must not both be active — they'd both try to manage the same vault.

---

Step 2 — Point at the plugin's scripts

The migration uses scripts bundled in the plugin. In a Claude session with the plugin active, ${CLAUDE_PLUGIN_ROOT} resolves to the install location. Define these once:

GBROOT="${CLAUDE_PLUGIN_ROOT}/skills/goldbrain-memory"   # if $CLAUDE_PLUGIN_ROOT isn't set, point this at the installed plugin's skills/goldbrain-memory folder
GB="$GBROOT/scripts/goldbrain.sh"      # validated REST client
MIG="$GBROOT/scripts/migrate.sh"       # the migrator
BOOT="$GBROOT/scripts/bootstrap.sh"    # repair / seed missing structure
LINT="$GBROOT/scripts/vault-lint.sh"   # health check
chmod +x "$GB" "$MIG" "$BOOT" "$LINT" 2>/dev/null

Quick reachability check (should print your current context, not an error):

"$GB" get _agent/context/current-context.md | head -5

If it says the vault is unreachable or returns 502, Obsidian or the Local REST API plugin isn't running on the backend — start it and retry before continuing.

---

Step 3 — Inspect the folders that will be retired (so nothing real is lost)

archive/ and decisions/by-project/ are being retired. On a vault that's only ever held placeholders, they're empty. But check first — if you put real notes there, relocate them before deleting:

"$GB" ls archive
"$GB" ls archive/projects ; "$GB" ls archive/notes ; "$GB" ls archive/imports
"$GB" ls decisions/by-project

If a listing shows real notes you want to keep:

• archive/projects/<x>.md → move to projects/archived/<x>.md (set status: archived).
• archive/notes/<x>.md → move to wherever it belongs (e.g. _agent/memory/episodic/ or resources/).
• decisions/by-project/<x>.md → the decision itself should already live in decisions/by-date/; if it's a unique record, move it there as YYYY-MM-DD-<slug>.md, then link it from the relevant project's ## Key Decisions.

Only placeholder README.md files are safe to remove without relocating.

---

Step 4 — Tell the migrator where to start (plant a version marker)

The migrator decides what to do by reading a version marker (_agent/goldbrain-vault.md). Your v0.2 vault predates that marker, so the migrator would otherwise refuse to run. Plant a "version 0" marker — a complete, valid marker tagged as the oldest schema — so the migrator runs every step from the beginning:

sed -e "s/{{DATE}}/$(date +%F)/g" -e "s/^schema_version: 2/schema_version: 0/" \
  "$GBROOT/scaffold/goldbrain-vault.md" | "$GB" put _agent/goldbrain-vault.md -

(The migrator bumps this marker to the current version automatically at the end of Step 6.)

---

Step 5 — Dry-run the migration (no changes yet)

"$MIG"

Read the printed plan. You should see lines like:

• [0->1] retire in-vault control docs (CLAUDE/BOOTSTRAP/STRUCTURE/index.md)
• [1->2] fold reviews/ into journal/ and _agent/health/
• move reviews/weekly/2026-W23.md -> journal/weekly/2026-W23.md (one line per review note you have)

Nothing has changed yet. This is the point to stop and confirm the plan looks right before applying.

---

Step 6 — Apply the migration

"$MIG" --apply

This moves your review notes into journal/ (and vault-health notes into _agent/health/), deletes the four in-vault control docs, and stamps the marker up to the current version. It is content-preserving: review notes are moved, not deleted.

---

Step 7 — Finish the cleanup the migrator doesn't cover

The migrator handles control docs and reviews/. These few items are removed by hand (after Step 3's inspection):

# spinup.md — the one control doc the migrator doesn't remove
"$GB" delete spinup.md

# archive/ and decisions/by-project/ — delete every file the Step 3 listings showed
"$GB" delete archive/README.md
"$GB" delete archive/projects/README.md
"$GB" delete archive/notes/README.md
"$GB" delete archive/imports/README.md
"$GB" delete decisions/by-project/README.md
# ...plus any other files those listings showed (Claude can enumerate and delete them for you)

Optional, cosmetic: replace the old verbose root README.md with the new thin signpost, and remove now-broken [[CLAUDE]] / [[BOOTSTRAP]] / [[STRUCTURE]] / [[index]] / [[spinup]] links from the ## Related sections of your current notes (leave old session logs alone — they're an accurate record of history):

"$GB" put README.md "$GBROOT/scaffold/README.vault.md"

---

Step 8 — Seed any missing new structure (repair pass)

"$BOOT"

bootstrap.sh is additive and never overwrites — it only fills in folders/templates the new layout expects and that aren't there yet (e.g. journal/quarterly, journal/annual, _agent/health, _agent/locks, the note templates). Safe to run any time.

---

Step 9 — Verify

GB_TODAY=$(date +%F) "$LINT"

Expected: vault-lint: clean — all invariants hold.

If it lists violations, they tell you exactly what's left:

• retired-path: spinup.md or archive/... or decisions/by-project/... → finish Step 7 (something didn't get removed).
• unknown-path: ... → a file is somewhere the new routing doesn't recognize; move it to a known home.
• frontmatter / folder/status notes → minor hygiene; fix at your leisure.

Then confirm your memory is intact:

"$GB" get _agent/memory/semantic/operator-preferences.md | head -20   # your profile
"$GB" ls _agent/sessions                                              # your session history
"$GB" ls journal/weekly                                               # reviews now live here

Or just ask Claude "load my goldbrain memory and tell me what you know about my active projects" and check that your preferences, projects, and recent sessions all come back.

When that looks right, you're done — and you can retire the Step 0 backup.

---

If something goes wrong

There's one rollback and it's simple: restore the Step 0 backup over the vault. Nothing in this process is irreversible as long as that backup exists. Then come back to it (or ask Jason) before retrying.

---

FAQ

Will the migration run automatically when I first use the new plugin? No. The plugin never runs the migrator on its own, and the destructive step always requires the explicit --apply above. On first load it would actually treat your marker-less vault as "needs setup" and could stamp it as already-current — which is exactly why Step 4 (planting a version-0 marker) is required to make the migrator engage. Do this once, deliberately, with a backup in hand.

Is any memory deleted? No memory notes. Only the old in-vault control docs (CLAUDE.md, BOOTSTRAP.md, STRUCTURE.md, index.md, spinup.md) and empty placeholder folders. Review notes are moved into the journal, not deleted.

Can I re-run the steps? bootstrap.sh and vault-lint.sh are safe to re-run anytime. After a successful migrate.sh --apply, re-running it just reports "up to date — nothing to do." If you ever need to re-trigger it, re-plant the version-0 marker (Step 4) first.

migrate: marker missing — run bootstrap.sh? You skipped Step 4. Plant the version-0 marker, then re-run the dry-run.

vault unreachable / 502? Obsidian or the Local REST API plugin isn't running on the backend (192.168.86.15:27124). Start it, confirm https://goldbrainapi.mpm.to responds, and retry.

---

What you're getting in v0.7.1

• A bundled, validated REST client (goldbrain.sh) that checks every write — a failed save can't silently look like success anymore.
• Faster session start (parallel context loading) and a one-line "where did we leave off" pointer.
• Search-before-write and idempotent appends — no more duplicate log lines or duplicated notes.
• Project lifecycle (incubating → active → on-hold → archived), inbox triage, and scope tracking.
• A monthly vault-health linter you can run any time (/gb-health).
• /gb-load, /gb-save, /gb-triage, /gb-health slash commands.
• A cooperative lock so Claude Code and CoWork sessions don't clobber each other.
• The em-dash / parenthesis PATCH-targeting fix from your issue tracker, baked in.