jason/goldbrain
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update to 0.7.1 and migration

Browse Source
This commit is contained in:
Jason Stedwell
2026-06-19 23:03:06 -05:00
parent 8bf9871dbe
commit aa00243987
60 changed files with 2026 additions and 576 deletions
Download Patch File Download Diff File Expand all files Collapse all files
goldbrain-memory.src/README.md
+48 -30
View File
@@ -2,27 +2,17 @@
Persistent memory for Claude via the **goldbrain** Obsidian vault, using the [Obsidian Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api).
Reads and writes notes across Claude/CoWork sessions using direct REST calls — no MCP server required. Built for **Bryan Gilliom** (CEO, Message Point Media) as the primary operator; Jason is the vault architect.
Reads and writes notes across Claude/CoWork sessions using direct REST calls — no MCP server required, but routed through a bundled validated client (`scripts/goldbrain.sh`) that status-checks every write. Built for **Bryan Gilliom** (CEO, Message Point Media) as the primary operator; Jason Stedwell is the vault architect.
**The plugin is the single source of truth.** All control logic — bootstrap/repair, operating contract, taxonomy, frontmatter conventions, and the canonical note templates — ships inside this plugin under `skills/goldbrain-memory/`. The vault itself holds **data only**: there are no `CLAUDE.md` / `BOOTSTRAP.md` / `STRUCTURE.md` / `index.md` control docs in it. This makes goldbrain self-bootstrapping (point it at an empty Obsidian vault and it stands up the full structure), easy to update (update the plugin, not the vault), and portable to any other vault.
## What it does
- Loads operator preferences, current context, and relevant project notes at the start of substantive conversations (parallel cold-start reads)
- Writes facts, preferences, and decisions Bryan asks Claude to remember — searching first so it updates rather than duplicates
- Manages project lifecycle (`incubating → active → on-hold/archived`) with folder/`status:` agreement
- Tracks scope switches, triages the inbox, and runs a monthly vault-health pass
- Loads operator preferences, current context, and relevant project notes at the start of substantive conversations
- Writes facts, preferences, and decisions Bryan asks Claude to remember
- Logs working sessions so future conversations can pick up where they left off
- Defers to the vault's own `BOOTSTRAP.md`/`CLAUDE.md`/`STRUCTURE.md` for structure and the operating contract
## What's new in 0.2
Adopts the procedural model from Jason's ECHO plugin (v0.5) while keeping goldbrain's in-vault control docs as the source of truth:
- Parallel context loading, **search-before-write**, and **append idempotency** (no more duplicate log lines)
- Project lifecycle folders and the folder/`status:` agreement rule
- **Scope switching** with a rolling Scope History, **inbox triage**, and a monthly **vault-health** check
- A **resilient daily Agent Log** routine that auto-creates the note/heading and avoids duplicate headings
- `operator-preferences.md` split into promoted **Fact / Pattern** rules vs. timestamped **Observations**
- **Em-dash / parenthesis bug fix:** heading PATCH targets now percent-encode special characters (em dash → `%E2%80%94`), with a GET→edit→PUT fallback and an ASCII-heading prevention rule
- **Bootstraps an empty vault from the bundled `scaffold/`** (folders, templates, anchor seeds, marker) and repairs/migrates an existing one via `scripts/bootstrap.sh` / `scripts/migrate.sh` — see `skills/goldbrain-memory/references/bootstrap.md`
- Exposes `/gb-load`, `/gb-save`, `/gb-triage`, `/gb-health` slash commands as explicit entry points, and coordinates concurrent Claude/CoWork sessions via a cooperative advisory lock
## Configuration
@@ -37,36 +27,64 @@ The endpoint presents a **valid TLS certificate**, so `-k` is not required. The
```
/vault/
├── CLAUDE.md STRUCTURE.md BOOTSTRAP.md spinup.md index.md README.md
├── README.md ← thin human signpost (not read for routing)
├── inbox/ (captures, imports, processing-log)
├── journal/ (daily, weekly, monthly, templates)
├── journal/ (daily, weekly, monthly, quarterly, annual, templates) — one time-series stream; rollups live here, not in a separate reviews/ tree
├── projects/ (active, incubating, on-hold, archived)
├── areas/ (business, personal, learning, systems)
├── resources/ (concepts, references, people, meetings, source-material)
├── decisions/ (by-date, by-project)
├── reviews/ (weekly, monthly, quarterly, annual)
├── archive/ (notes, projects, imports)
├── resources/ (companies, concepts, references, people, meetings)
├── decisions/ (by-date)
└── _agent/
├── goldbrain-vault.md ← bootstrap marker (schema_version + date)
├── context/ ← task-scoped context bundles
├── memory/ ← working / episodic / semantic
├── sessions/ ← YYYY-MM-DD-HHMM-<slug>.md
├── templates/ ← canonical note templates
├── outputs/ ← briefs / drafts / summaries / synthesis
├── health/ ← YYYY-MM-vault-health.md (monthly self-maintenance audit)
├── templates/ ← canonical note templates (seeded from the plugin's scaffold/)
├── skills/ ← active / archived
└── heartbeat/
├── heartbeat/ ← last-session.md orientation pointer (read at load, written at session end)
└── locks/ ← vault.lock — cooperative advisory multi-writer lock
```
## First run
Control logic and the master scaffold live in the plugin, not the vault:
The vault ships its own `BOOTSTRAP.md`. On first use the skill reads `/vault/BOOTSTRAP.md`; if present it follows that preflight, and if absent (a fresh empty vault) it offers to bootstrap.
```
commands/ ← slash commands: gb-load, gb-save, gb-triage, gb-health
skills/goldbrain-memory/
├── SKILL.md ← operating procedure (authoritative)
├── references/
│ ├── operating-contract.md ← durable principles + safety + concurrency
│ ├── bootstrap.md ← bootstrap / repair / migrate an empty vault
│ ├── vault-layout.md ← canonical layout + frontmatter
│ ├── routing-map.md ← complete endpoint→logic map (human authority)
│ ├── api-reference.md ← REST endpoint patterns + routing map
│ └── session-log-template.md
├── scripts/
│ ├── goldbrain.sh ← validated API client (auth, status-check, retry, verify, lock, scope)
│ ├── routing.json ← canonical machine-readable route manifest (linter enforces it)
│ ├── vault-lint.sh ← read-only invariant checker (monthly Vault Health pass)
│ ├── bootstrap.sh ← deterministic, idempotent vault setup/repair
│ └── migrate.sh ← deterministic schema migration (dry-run by default)
└── scaffold/ ← verbatim files the bootstrap writes into the vault
├── README.vault.md goldbrain-vault.md
├── templates/ (8 note templates)
└── anchors/ (operator-preferences, current-context, inbox seeds)
```
## Skills
## Skills & commands
| Skill | Triggers |
|-------|----------|
| `goldbrain-memory` | "remember that", "save to memory", "what do you know about me", "load my profile", "check my notes", "log this decision", "add to my inbox" — and proactively at the start of substantive conversations |
| 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 `vault-lint.sh` and summarize invariant violations |
## Requirements
- Obsidian running on the backend with the [Local REST API plugin](https://github.com/coddingtonbear/obsidian-local-rest-api) enabled (binding host `0.0.0.0`)
- Obsidian running on the backend (`192.168.86.15:27124`) with the [Local REST API plugin](https://github.com/coddingtonbear/obsidian-local-rest-api) enabled (binding host `0.0.0.0`)
- HTTPS access to `https://goldbrainapi.mpm.to` from the Claude/CoWork session environment