135 lines
6.7 KiB
Markdown
135 lines
6.7 KiB
Markdown
# 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](https://github.com/coddingtonbear/obsidian-local-rest-api) active and reverse-proxied to `goldbrainapi.mpm.to`
|
||
|