Jason Stedwell
107 lines
6.4 KiB
Markdown
107 lines
6.4 KiB
Markdown
# 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.
|