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:

```bash
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):

```bash
"$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:

```bash
"$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:

```bash
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)

```bash
"$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

```bash
"$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):

```bash
# 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):

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

---

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

```bash
"$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

```bash
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:

```bash
"$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.