diff --git a/skills/goldbrain-memory/references/api-reference.md b/skills/goldbrain-memory/references/api-reference.md new file mode 100644 index 0000000..d1bd3ec --- /dev/null +++ b/skills/goldbrain-memory/references/api-reference.md @@ -0,0 +1,221 @@ +# Goldbrain — Obsidian Local REST API Reference + +Server: `https://goldbrainapi.mpm.to` (reverse proxy → Obsidian Local REST API on `192.168.86.15:27124`) +Auth header: `Authorization: Bearer ` +The endpoint has a **valid TLS certificate** — `-k` is not required. Paths address the vault at its **root**. + +--- + +## Reading Files + +```bash +# Read any file by vault path +curl -s \ + -H "Authorization: Bearer " \ + "https://goldbrainapi.mpm.to/vault/_agent/context/current-context.md" +``` + +Returns raw file content (text/markdown). On 404, the file does not exist. + +```bash +# Read a specific heading's content only +curl -s \ + -H "Authorization: Bearer " \ + "https://goldbrainapi.mpm.to/vault/_agent/memory/semantic/operator-preferences.md/heading/Operator" +``` + +Nested headings: separate levels with `::` (URL-encode spaces as `%20`): +``` +/vault/path/to/note.md/heading/Work%3A%3AMeetings +``` + +--- + +## Listing Directories + +```bash +# List contents of a directory (trailing slash required) +curl -s \ + -H "Authorization: Bearer " \ + "https://goldbrainapi.mpm.to/vault/_agent/sessions/" +``` + +Returns JSON: `{ "files": [...], "folders": [...] }`. + +--- + +## Appending Content (POST) + +`POST` appends to the **end** of an existing file. Creates the file if it doesn't exist. + +```bash +cat > /tmp/obs_entry.md << 'OBSEOF' +- 2026-06-02: your entry here +OBSEOF + +curl -s -X POST \ + -H "Authorization: Bearer " \ + -H "Content-Type: text/markdown" \ + --data-binary @/tmp/obs_entry.md \ + "https://goldbrainapi.mpm.to/vault/inbox/captures/inbox.md" +``` + +--- + +## Creating or Overwriting Files (PUT) + +`PUT` creates a new file or fully overwrites an existing one. Intermediate directories are created automatically. + +```bash +cat > /tmp/obs_file.md << 'OBSEOF' +--- +type: session-log +status: complete +created: 2026-06-02 +updated: 2026-06-02 +tags: [agent, session] +agent_written: true +source_notes: [] +--- + +# content here + +## Related +- [[projects/active/some-project]] +OBSEOF + +curl -s -X PUT \ + -H "Authorization: Bearer " \ + -H "Content-Type: text/markdown" \ + --data-binary @/tmp/obs_file.md \ + "https://goldbrainapi.mpm.to/vault/_agent/sessions/2026-06-02-1430-my-session.md" +``` + +--- + +## Patching a Specific Section (PATCH) + +`PATCH` edits inside a file without rewriting it. Target and operation are set via headers. + +### Append under a heading + +**Heading targets must be the FULL heading path, `::`-delimited from the top-level heading.** A bare subheading name returns `400 invalid-target` (errorCode 40080). Example: `## Fact / Pattern` nested under `# Operator Preferences` → `Target: Operator Preferences::Fact / Pattern`. Percent-encode non-ASCII characters (e.g. `H%C3%A9llo`); spaces are fine. + +> **Special characters in heading targets (em dashes, parentheses) — known failure.** The server matches the `Target` header against heading text only after URL-decoding it, and the matcher applies regex-special handling to characters like `(` `)` `[` `]`. A heading such as `# EarthDnD — Personal Project` targeted literally fails with `invalid-target` (40080), because the raw em dash (`—`, U+2014) rides unreliably in an HTTP header. Handle it in this priority order: +> +> 1. **Prevent — keep new headings ASCII.** When you author a heading you might later PATCH, use a plain hyphen with spaces (` - `), never an em dash/en dash, and avoid parentheses/brackets. `# EarthDnD - Personal Project` is always PATCH-safe. This is the durable fix. +> 2. **Percent-encode the offending run** when targeting an existing special-char heading: em dash `—` → `%E2%80%94`, en dash `–` → `%E2%80%93`. Example fixing the bug-report case: `Target: EarthDnD %E2%80%94 Personal Project::AI Platform Roles`. +> 3. **Fallback (GET → edit → PUT)** when even encoding fails (e.g. parentheses): read the whole file, edit the section in memory, PUT it back. Atomic, not in-place — small race-condition risk on hot files, so prefer fixing the heading to ASCII. + +| Character | Glyph | Percent-encoding | +|-----------|-------|------------------| +| Em dash | `—` (U+2014) | `%E2%80%94` | +| En dash | `–` (U+2013) | `%E2%80%93` | +| Space | ` ` | `%20` (literal space also works) | +| `::` (nesting, in URL path only) | `::` | `%3A%3A` | +| é (example accented char) | `é` | `%C3%A9` | + +```bash +cat > /tmp/obs_patch.md << 'OBSEOF' +Bryan prefers concise status updates — lead with the decision. +OBSEOF + +curl -s -X PATCH \ + -H "Authorization: Bearer " \ + -H "Operation: append" \ + -H "Target-Type: heading" \ + -H "Target: Operator Preferences::Fact / Pattern" \ + -H "Content-Type: text/markdown" \ + --data-binary @/tmp/obs_patch.md \ + "https://goldbrainapi.mpm.to/vault/_agent/memory/semantic/operator-preferences.md" +``` + +### Discover heading / block / frontmatter targets + +When unsure of the exact heading path, GET the note with the document-map Accept header: + +```bash +curl -s \ + -H "Authorization: Bearer " \ + -H "Accept: application/vnd.olrapi.document-map+json" \ + "https://goldbrainapi.mpm.to/vault/_agent/memory/semantic/operator-preferences.md" +``` + +Returns `{ "headings": [...], "blocks": [...], "frontmatterFields": [...] }`. Copy the heading string verbatim into `Target`. + +### Replace a heading's content entirely + +Same call with `Operation: replace` — e.g. to refresh a project's `Project Name::Current status`. + +### Prepend under a heading + +Same call with `Operation: prepend`. + +### Patch a frontmatter field + +```bash +curl -s -X PATCH \ + -H "Authorization: Bearer " \ + -H "Operation: replace" \ + -H "Target-Type: frontmatter" \ + -H "Target: updated" \ + -H "Content-Type: application/json" \ + --data '"2026-06-02"' \ + "https://goldbrainapi.mpm.to/vault/projects/active/vault-foundation.md" +``` + +--- + +## Searching + +```bash +curl -s -X POST \ + -H "Authorization: Bearer " \ + "https://goldbrainapi.mpm.to/search/simple/?query=weekly+review" +``` + +Returns an array of `{ filename, score, matches: [{ context, match }] }`. + +--- + +## Deleting Files + +```bash +curl -s -X DELETE \ + -H "Authorization: Bearer " \ + "https://goldbrainapi.mpm.to/vault/archive/notes/old-note.md" +``` + +Only on explicit operator request. Deletion is destructive. + +--- + +## URL-Encoding Notes + +- Path separators (`/`) in the vault path are **literal** — do not encode them. +- Spaces in filenames or heading targets in a URL: use `%20`. +- Nested heading levels in a URL path: use `%3A%3A` for `::`. +- Heading text in the `Target:` header: the **full heading path** joined by `::` (e.g. `Operator Preferences::Fact / Pattern`), no `#`; spaces are fine; **percent-encode non-ASCII and regex-special characters** — em dash `—` → `%E2%80%94`, en dash `–` → `%E2%80%93` (see the special-characters note under *Patching* above). Best practice: keep heading text ASCII so targets never need encoding. + +--- + +## Memory Routing Map + +| Situation | Vault path | Method | +|-----------|-----------|--------| +| Quick capture / unsorted | `inbox/captures/inbox.md` (date-prefixed line) | POST | +| Raw imported material | `inbox/imports/` | PUT | +| Operator preference / durable fact | `_agent/memory/semantic/operator-preferences.md` | PATCH | +| Other durable facts, patterns | `_agent/memory/semantic/.md` | PUT | +| Event record (what happened) | `_agent/memory/episodic/.md` | PUT | +| Short-lived, time-boxed state | `_agent/memory/working/.md` | PUT | +| Task-scoped context / focus | `_agent/context/current-context.md` | PATCH / PUT | +| Working-session log | `_agent/sessions/YYYY-MM-DD-HHMM-.md` | PUT | +| Long-running project state | `projects//.md` (lifecycle: `incubating` → `active` → `on-hold`/`archived`; folder and `status:` MUST agree) | PUT + PATCH | +| Non-obvious decision (ADR) | `decisions/by-date/YYYY-MM-DD-.md` (mirror `by-project/`) | PUT | +| Person context | `resources/people/.md` | PUT / PATCH | +| Concept / reference note | `resources/concepts/` or `resources/references/` | PUT | +| Daily activity / Agent Log | `journal/daily/YYYY-MM-DD.md` | POST / PATCH | +| Periodic review | `reviews/{weekly,monthly,quarterly,annual}/` | PUT | + +**Slug rules:** kebab-case, ASCII, ~40 chars max. Every file carries canonical frontmatter (see `vault-layout.md`).