goldbrain

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, so context survives from one conversation to the next.


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`

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.

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

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).
The endpoint and API key are baked into the plugin; there's nothing to configure.
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, 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 <text>`	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.

6.4 KiB Raw Permalink Blame History