From 3f687bc4712d4e40eece69c71e8813dc51f63848 Mon Sep 17 00:00:00 2001 From: Jason Stedwell Date: Fri, 19 Jun 2026 23:09:06 -0500 Subject: [PATCH] update to 0.7.1 and migration --- README.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 102 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 1120f89..7c7f997 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,106 @@ -# Goldbrain Memory Vault +# goldbrain -This Obsidian vault is the persistent memory substrate ("second brain") for its operator. It is read and written across Claude / CoWork sessions through the Obsidian Local REST API. +Bryan's persistent-memory **Obsidian vault** plus the **`goldbrain-memory`** Claude Code / CoWork plugin that drives it. Claude reads and writes this vault across sessions through the [Obsidian Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api), so context survives from one conversation to the next. -**This vault holds data, not logic.** All operating procedure — how the vault is bootstrapped, how notes are routed, the taxonomy, frontmatter conventions, and safety rules — lives in the **`goldbrain-memory` plugin**, which is the single source of truth. There are intentionally no `CLAUDE.md` / `BOOTSTRAP.md` / `STRUCTURE.md` control docs in this vault; updating or porting goldbrain means updating or installing the plugin, not editing files here. +| | | +|---|---| +| **Operator** | Bryan Gilliom (CEO, Message Point Media) | +| **Architect** | Jason Stedwell | +| **Plugin version** | `goldbrain-memory` v0.7.1 | +| **Endpoint** | `https://goldbrainapi.mpm.to` (reverse proxy → Obsidian Local REST API on `192.168.86.15:27124`) | +| **Repo** | `git.alwisp.com/jason/goldbrain` | -- **Layout:** see the plugin's `references/vault-layout.md`. -- **Operating contract & safety:** see the plugin's `references/operating-contract.md`. -- **Bootstrap / repair:** see the plugin's `references/bootstrap.md`. -- **Version marker:** `_agent/goldbrain-vault.md` records the schema version and bootstrap date. +> Sibling vault: Jason's personal **ECHO** vault runs the same engine. They are separate memories — do not cross-write. Bryan's facts live here; Jason's live in ECHO. -Folders: `inbox/`, `journal/` (daily + weekly/monthly/quarterly/annual rollups), `projects/`, `areas/`, `resources/`, `decisions/`, and the agent subtree `_agent/`. +--- + +## What's in this repo + +``` +goldbrain/ +├── goldbrain-memory.src/ ← plugin source (edit here) +│ ├── .claude-plugin/plugin.json +│ ├── commands/ ← /gb-load · /gb-save · /gb-triage · /gb-health +│ └── skills/goldbrain-memory/ +│ ├── SKILL.md ← operating procedure (authoritative) +│ ├── references/ ← operating-contract · vault-layout · routing-map · bootstrap · api-reference +│ ├── scripts/ ← goldbrain.sh · vault-lint.sh · routing.json · bootstrap.sh · migrate.sh +│ └── scaffold/ ← files the bootstrap seeds into an empty vault +├── goldbrain-memory.plugin ← installable bundle (canonical) +├── goldbrain-memory-0.7.1.plugin ← installable bundle (versioned) +├── migrate.md ← upgrade guide: v0.2 → v0.7.1 (give this to Bryan) +├── .env.example ← local env template +├── .source-references/ ← historical snapshots + REST key/address reference +│ +└── (vault data, root-addressed) + ├── inbox/ journal/ projects/ areas/ + ├── resources/ decisions/ _agent/ + └── _agent/goldbrain-vault.md ← bootstrap/version marker +``` + +The vault content (`inbox/`, `journal/`, `projects/`, …) and the plugin live in the same repo: the plugin is the engine, the rest is Bryan's data. + +--- + +## Architecture — the plugin is the single source of truth + +As of v0.7.1 the **vault holds data only.** All operating logic — bootstrap/repair, taxonomy, routing, frontmatter conventions, safety rules — ships **inside the plugin**, not in the vault. There are intentionally **no** `CLAUDE.md` / `BOOTSTRAP.md` / `STRUCTURE.md` / `index.md` control docs in the vault; updating or porting goldbrain means updating or installing the plugin, not editing files in the vault. + +The "is this vault set up?" probe is the marker `_agent/goldbrain-vault.md` (it records the schema version + bootstrap date). Point the plugin at any empty Obsidian vault and `bootstrap.sh` stands up the full structure from `scaffold/`. + +--- + +## Install + +1. Install **`goldbrain-memory-0.7.1.plugin`** in Claude Code / CoWork (remove any older `goldbrain-memory` first — two copies must not manage the same vault at once). +2. The endpoint and API key are baked into the plugin; there's nothing to configure. +3. Confirm it loaded — ask Claude *"load my goldbrain memory."* + +**Backend requirement:** Obsidian running on `192.168.86.15:27124` with the Local REST API plugin enabled (binding host `0.0.0.0`), reachable over HTTPS at `https://goldbrainapi.mpm.to`. + +## Upgrading from v0.2 + +v0.7.1 changes the vault structure (retires the in-vault control docs, folds `reviews/` into `journal/`, retires `archive/` and `decisions/by-project/`). **It does not run automatically, and done correctly it is not lossy** — follow [`migrate.md`](migrate.md), which preserves all memory data and backs everything up first. + +## Using it + +Talk to Claude normally — it loads context at the start of substantive sessions and persists what you ask it to remember. Explicit entry points: + +| Command | Does | +|---------|------| +| `/gb-load` | Cold-start context read (profile, scope, latest session, today, inbox) | +| `/gb-save ` | Route + persist content to its canonical home (search-first, idempotent) | +| `/gb-triage` | Drain aging inbox captures to their homes, logging each move | +| `/gb-health` | Run the `vault-lint.sh` invariant checker and summarize findings | + +--- + +## Vault layout (root-addressed) + +``` +inbox/ captures · imports · processing-log +journal/ daily · weekly · monthly · quarterly · annual · templates (one time-series stream; rollups live here, not a separate reviews/ tree) +projects/ active · incubating · on-hold · archived (folder == status: frontmatter) +areas/ business · personal · learning · systems (standing responsibilities, no end state) +resources/ people · companies · concepts · references · meetings · source-material +decisions/ by-date/ (ADRs; mirror into a project's ## Key Decisions via wikilink) +_agent/ goldbrain-vault.md (marker) · context · memory{working,episodic,semantic} + sessions · health · heartbeat · locks · skills{active,archived} + templates · outputs{briefs,drafts,summaries,synthesis} +``` + +Full detail in the plugin's references: `vault-layout.md` (layout + frontmatter), `routing-map.md` (every write destination), `operating-contract.md` (principles + safety), `bootstrap.md` (setup/repair/migrate), `api-reference.md` (REST patterns). + +`_agent/outputs/` and `resources/source-material/` are goldbrain-specific (the plugin carries routes for them); everything else mirrors the shared engine. + +--- + +## Maintenance + +- `goldbrain.sh` is the validated REST client — it status-checks every write, so a failed save can't masquerade as success. Prefer it over hand-built `curl`. +- `vault-lint.sh` (also via `/gb-health`) checks structural invariants — folder/`status:` agreement, duplicate slugs, retired/unknown paths, frontmatter integrity, scope drift. Run it monthly or any time. +- The vault is shared (Claude Code **and** CoWork); a cooperative advisory lock (`_agent/locks/`) coordinates concurrent writers. + +## Known issue handled in-plugin + +PATCH heading-target failures on em dashes / parentheses (`invalid-target`, errorCode 40080) are documented and worked around in `SKILL.md` and `references/api-reference.md`: keep headings ASCII, percent-encode the offending run (`—` → `%E2%80%94`), or fall back to GET→edit→PUT.