update to 0.7.1 and migration
This commit is contained in:
Jason Stedwell
+243
@@ -0,0 +1,243 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user