goldbrain-memory/README.md

goldbrain-memory

Persistent memory for Bryan Gilliom via the goldbrain Obsidian vault over the Local REST API. Reads and writes notes across Claude/CoWork sessions — no MCP server required.

Version: 1.2.0
Author: Jason
Repo: https://git.mpm.to/mpm/goldbrain-memory
CoWork Project: CW-022 — Goldbrain Memory

Security note: This repo contains sanitized documentation only. The bearer token and fully configured file are stored privately in the CoWork folder (Bryan Gilliom, Google Drive). Do not commit credentials here.

---

Overview

goldbrain-memory gives Claude durable, cross-session memory by reading from and writing to Bryan Gilliom's personal Obsidian vault via a REST API hosted at goldbrainapi.mpm.to. Unlike MCP-based memory tools, this plugin makes direct HTTPS calls from the bash sandbox — no companion server process, no daemon, no port forwarding. The vault holds Bryan's operator preferences, active projects, session logs, daily notes, inbox captures, decisions, and person context. The plugin reads context at session start, writes facts and decisions as they emerge, and logs outcomes at session end.

---

Skills

Skill	What It Does
goldbrain-memory	Use the goldbrain Obsidian vault as persistent memory. Triggers on: remember, save, note, log, capture, "what do you know about me", "check my notes", "load my memory/profile", "what did we discuss before", "pick up where we left off", "anything on X before my meeting?", "add to my inbox", "track this project". Also fires proactively at session start (context load) and end (session log).

---

API Configuration

Field	Value
Base URL	https://goldbrainapi.mpm.to
Auth	Authorization: Bearer <OBSIDIAN_BEARER_TOKEN>
TLS	Valid cert — no -k flag needed
Transport	HTTPS REST (Obsidian Local REST API plugin)

---

Reference Files

File	Purpose
references/api-reference.md	Complete endpoint reference — every GET/POST/PUT/PATCH/DELETE pattern, heading target rules, search API
references/vault-layout.md	Folder structure, YAML frontmatter conventions, file naming rules
references/bootstrap.md	Empty vault setup and repair checklist
references/session-log-template.md	Canonical template for session log files

---

Workflow Notes

Session Start — Parallel Context Load

Five GETs issued in parallel (not sequential) for ~3× speed:

1. GET /vault/BOOTSTRAP.md — preflight/repair manifest
2. GET /vault/_agent/memory/semantic/operator-preferences.md — Bryan's profile
3. GET /vault/_agent/context/current-context.md — active scope + scope history
4. GET /vault/_agent/sessions/ — listing; read the 5 most recent by reverse-lex sort
5. GET /vault/journal/daily/YYYY-MM-DD.md — today's note

Memory loading is silent — no narration to Bryan.

Write Rules

• Search before write — always POST /search/simple/?query=<slug> before creating any new note. A duplicate may exist in a different lifecycle folder.
• Read before append — GET the target file and check for the exact line before POST-appending. POST is not idempotent.
• PATCH heading targets use full :: paths (e.g. Operator Preferences::Fact / Pattern). Always GET the document map first. Keep heading text ASCII (no em dashes or parentheses) to avoid PATCH errors.
• Bump updated: after meaningful content changes; skip for routine log appends.

Project Lifecycle

Projects move through projects/incubating/ → projects/active/ → projects/on-hold/ → projects/archived/. Folder and status: frontmatter must always agree.

Scope Switching

_agent/context/current-context.md holds a single active scope. On scope change: PATCH-prepend the prior scope to ## Scope History, PATCH-replace ## Scope with new scope, bump updated:.

Daily Agent Log

After substantive activity, PATCH-append a one-liner to journal/daily/YYYY-MM-DD.md under ## Agent Log. The skill handles auto-creation of missing daily notes and missing headings.

Monthly Vault Health

On the first substantive session of each calendar month: check for stale active projects (>30 days), unprocessed inbox items (>14 days), duplicate slugs across lifecycle folders, and broken heading targets.

---

Write Routing

Situation	Path	Method
Quick capture / unsorted	inbox/captures/inbox.md	POST
Operator preference / durable fact	_agent/memory/semantic/operator-preferences.md	PATCH
Other durable fact	_agent/memory/semantic/<slug>.md	PUT
Event record	_agent/memory/episodic/<slug>.md	PUT
Short-lived working state	_agent/memory/working/<slug>.md	PUT
Active scope	_agent/context/current-context.md	PATCH/PUT
Session log	_agent/sessions/YYYY-MM-DD-HHMM-<slug>.md	PUT
Project state	projects/<lifecycle>/<slug>.md	PUT + PATCH
Decision (ADR)	decisions/by-date/YYYY-MM-DD-<slug>.md	PUT
Person context	resources/people/<name>.md	PUT/PATCH
Daily activity	journal/daily/YYYY-MM-DD.md	PATCH (auto-create)

---

Setup

No server to install. The vault REST API is already running at goldbrainapi.mpm.to. The plugin is self-contained — install via CoWork Settings → Plugins → Install from file, selecting goldbrain-memory.plugin.

Checklist

• Install goldbrain-memory.plugin in CoWork
• Verify vault is reachable: curl -s -H "Authorization: Bearer <OBSIDIAN_BEARER_TOKEN>" https://goldbrainapi.mpm.to/vault/BOOTSTRAP.md | head -5
• Confirm BOOTSTRAP.md, _agent/memory/semantic/operator-preferences.md, and _agent/context/current-context.md exist (404 = vault not bootstrapped; see references/bootstrap.md)

---

Troubleshooting

Symptom	Fix
502 Bad Gateway from API	Obsidian is not running on the backend host — start Obsidian and the Local REST API plugin
400 invalid-target (errorCode 40080) on PATCH	Heading target is wrong — GET the document map first; check for em dashes or parentheses in the heading and percent-encode them
Duplicate notes appearing	Search-before-write rule was skipped — search all lifecycle folders before creating any new slug-addressed note
POST append created duplicate lines	Read-before-append rule was skipped — GET file and substring-check before POST
Session log missing HHMM	Filename must be YYYY-MM-DD-HHMM-<slug>.md — older logs without HHMM are legacy; all new ones require the four-digit time component

---

Requirements

• CoWork (Claude Desktop with plugin support)
• Obsidian running on backend with Local REST API plugin active and reverse-proxied to goldbrainapi.mpm.to