jason/goldbrain

Fork 0

Files

T

jason 392ae7bbe3 first push

2026-06-04 16:20:56 -05:00

7.7 KiB

Raw Blame History

type, status, created, updated, tags, agent_written, source_notes

type

status

created

updated

Obsidian Local REST API

Summary

This is the operational command reference for reaching the goldbrain vault over the Obsidian Local REST API. It is the contract a CoWork plugin or any REST client follows to read and write memory. Paths address the vault at its root (e.g. /vault/_agent/...), matching the layout defined in STRUCTURE and verified by BOOTSTRAP.

Connection

Setting	Value
Base URL	`https://goldbrainapi.mpm.to`
Auth	`Authorization: Bearer <key>` on every request
Content type (writes)	`text/markdown` (or `application/json` for frontmatter patches)

Never store the key in the vault. It lives in the local environment / plugin config, not in any note. The examples below read it from the shell:

export OBSIDIAN_REST_API_URL="https://goldbrainapi.mpm.to"
export OBSIDIAN_REST_API_KEY="<bearer-token>"
AUTH="Authorization: Bearer ${OBSIDIAN_REST_API_KEY}"
BASE="${OBSIDIAN_REST_API_URL}"

TLS note: goldbrainapi.mpm.to presents a valid certificate (reverse proxy → 192.168.86.15:27124), so -k is not needed. Add -k only if the endpoint is ever switched to a self-signed certificate.

Reading Files

curl -s -H "$AUTH" "$BASE/vault/_agent/context/current-context.md"

Returns raw file content (text/markdown). A 404 means the file does not exist.

# Read only one heading's content (full heading path, :: delimited)
curl -s -H "$AUTH" \
  "$BASE/vault/_agent/memory/semantic/operator-preferences.md/heading/Operator%20Preferences%3A%3AFact%20%2F%20Pattern"

Listing Directories

curl -s -H "$AUTH" "$BASE/vault/_agent/sessions/"   # trailing slash required

Returns JSON: { "files": [...], "folders": [...] }.

Appending Content (POST)

POST appends to the end of an existing file; it creates the file if absent.

cat > /tmp/obs_entry.md << 'OBSEOF'
- 2026-06-02: quick note to triage later
OBSEOF

curl -s -X POST -H "$AUTH" -H "Content-Type: text/markdown" \
  --data-binary @/tmp/obs_entry.md \
  "$BASE/vault/inbox/captures/inbox.md"

Creating or Overwriting Files (PUT)

PUT creates a new file or fully overwrites one. Missing parent directories are created automatically.

cat > /tmp/obs_file.md << 'OBSEOF'
---
type: session-log
status: complete
created: 2026-06-02
updated: 2026-06-02
tags: []
agent_written: true
source_notes: []
---

# Session: <title>

## Related
- [[projects/active/some-project]]
OBSEOF

curl -s -X PUT -H "$AUTH" -H "Content-Type: text/markdown" \
  --data-binary @/tmp/obs_file.md \
  "$BASE/vault/_agent/sessions/2026-06-02-1430-my-session.md"

Include the canonical frontmatter (see STRUCTURE / BOOTSTRAP §4) and set agent_written: true on agent-generated notes. Cross-reference links go in a body ## Related section, never in frontmatter.

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). Verified against API v4.1.2. Example: ## Fact / Pattern under # Operator Preferences → Target: Operator Preferences::Fact / Pattern. Percent-encode non-ASCII; spaces are fine.

cat > /tmp/obs_patch.md << 'OBSEOF'
Bryan prefers concise status updates — lead with the decision.
OBSEOF

curl -s -X PATCH -H "$AUTH" \
  -H "Operation: append" \
  -H "Target-Type: heading" \
  -H "Target: Operator Preferences::Fact / Pattern" \
  -H "Content-Type: text/markdown" \
  --data-binary @/tmp/obs_patch.md \
  "$BASE/vault/_agent/memory/semantic/operator-preferences.md"

To discover exact heading paths, GET the note with Accept: application/vnd.olrapi.document-map+json; it 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

curl -s -X PATCH -H "$AUTH" \
  -H "Operation: replace" \
  -H "Target-Type: frontmatter" \
  -H "Target: updated" \
  -H "Content-Type: application/json" \
  --data '"2026-06-02"' \
  "$BASE/vault/projects/active/vault-foundation.md"

Use this to keep updated: and status: current after a write.

Searching

curl -s -X POST -H "$AUTH" "$BASE/search/simple/?query=weekly+review"

Returns an array of { filename, score, matches: [{ context, match }] }.

Deleting Files

curl -s -X DELETE -H "$AUTH" "$BASE/vault/archive/notes/old-note.md"

Only on an explicit request. Deletion is destructive; memory is append-friendly.

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 fine; percent-encode non-ASCII.

Memory Routing Map

Where each kind of write lands in goldbrain (mirrors BOOTSTRAP §3 and the taxonomy in STRUCTURE).

Situation	Vault path	Method
Unsorted / quick capture	`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/<slug>.md`	PUT
Event record (what happened)	`_agent/memory/episodic/<slug>.md`	PUT
Short-lived, time-boxed state	`_agent/memory/working/<slug>.md`	PUT
Task-scoped context / focus	`_agent/context/current-context.md`	PATCH / PUT
Working-session log	`_agent/sessions/YYYY-MM-DD-HHMM-<slug>.md`	PUT
Long-running project state	`projects/active/<slug>.md`	PUT + PATCH
Non-obvious decision (ADR)	`decisions/by-date/YYYY-MM-DD-<slug>.md` (mirror `by-project/`)	PUT
Person context	`resources/people/<name>.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 (no [[wikilinks]] in it).

Plugin Readiness Checklist

Base URL reachable; returns 401 without the key, content with it.
GET /vault/BOOTSTRAP.md succeeds (vault bootstrapped — else run BOOTSTRAP).
A test PUT into _agent/sessions/ creates the file and parent dirs.
A PATCH Target-Type: heading append with a full :: path lands under the right heading.
POST /search/simple/?query=... returns scored matches.
Key supplied via env / plugin config only — never written into a note.

Sources / Notes

Adapted from the working obsidian-memory plugin reference, retargeted to goldbrain's vault-root layout and the goldbrainapi.mpm.to host. Record host-binding or plugin-specific conventions here as they emerge.

7.7 KiB Raw Blame History