# 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](https://github.com/coddingtonbear/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

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 <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.