update to 0.7.1 and migration
This commit is contained in:
Jason Stedwell
@@ -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`.
|
> 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.
|
||||||
- **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.
|
|
||||||
|
|
||||||
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 <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.
|
||||||
|
|||||||
Reference in New Issue
Block a user