docs: add README v1.2.0
This commit is contained in:
@@ -0,0 +1,131 @@
|
|||||||
|
# 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
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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 fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8` |
|
||||||
|
| 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 fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" 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`
|
||||||
Reference in New Issue
Block a user