jason/echo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

plugin 0.2.2

Browse Source
This commit is contained in:
jason
2026-06-05 00:49:20 -05:00
parent 67acf8fd52
commit d37b248747
115 changed files with 5565 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.references/goldbrain-memory/skills/goldbrain-memory/SKILL.md
+233
View File
@@ -0,0 +1,233 @@
---
name: goldbrain-memory
description: Use the goldbrain Obsidian vault as persistent memory across Claude/CoWork sessions. Triggers when the operator says "remember that", "remember this", "save to memory", "what do you know about me", "load my memory", "load my profile", "what did we discuss before", "check my notes", "what's my context", "what are my preferences", "log this decision", "add to my inbox", or starts a new project that should be tracked. Also triggers proactively at the start of substantive conversations to load operator context, and at the end to log session outcomes.
---
# Goldbrain Memory
Use the **goldbrain** Obsidian vault as persistent memory. Read context accumulated across sessions; write things the operator asks to be remembered.
The primary operator is **Bryan Gilliom** (CEO, Message Point Media). Unless stated otherwise, "the operator" means Bryan. Jason is the vault's architect, not the day-to-day user. Write memory in third person ("Bryan prefers X", not "I prefer X").
## API Configuration
All calls use these constants — hardcoded for this personal plugin:
```
OBSIDIAN_BASE = https://goldbrainapi.mpm.to
OBSIDIAN_KEY = fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8
```
The endpoint has a **valid TLS certificate**, so `-k` is not needed (add it only if the cert ever changes to self-signed). Always pass the `Authorization: Bearer` header. Paths address the vault **at its root** (e.g. `/vault/_agent/...`).
Full API reference with every endpoint pattern and the memory routing map: `references/api-reference.md`. Vault layout and frontmatter conventions: `references/vault-layout.md`.
## When to Load Memory
Load at the start of any substantive conversation — anything beyond a single quick factual question. The signal: the operator is starting work, planning, asking for help with something that has state, or referencing prior discussions.
Do NOT narrate this loading. Reading memory is expected behavior.
### Loading procedure
**Step 1 — Confirm the vault is bootstrapped:**
```bash
curl -s \
-H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
"https://goldbrainapi.mpm.to/vault/BOOTSTRAP.md"
```
If this returns 404, the vault is not set up. Follow `references/bootstrap.md` before doing anything else.
**Step 2 — Read operator preferences (the profile):**
```bash
curl -s \
-H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
"https://goldbrainapi.mpm.to/vault/_agent/memory/semantic/operator-preferences.md"
```
**Step 3 — Read active context and the latest session:**
```bash
# Current task-scoped context bundle
curl -s -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
"https://goldbrainapi.mpm.to/vault/_agent/context/current-context.md"
# List recent session logs, then read the most relevant
curl -s -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
"https://goldbrainapi.mpm.to/vault/_agent/sessions/"
```
**Step 4 — If a specific project is in play, list active projects and read the best match:**
```bash
curl -s -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
"https://goldbrainapi.mpm.to/vault/projects/active/"
curl -s -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
"https://goldbrainapi.mpm.to/vault/projects/active/<slug>.md"
```
Optionally read today's daily note at `/vault/journal/daily/YYYY-MM-DD.md` for current priorities and open loops.
## When to Write Memory
Write when the operator:
- States a fact, preference, or commitment worth keeping ("I prefer X", "we use uv not pip", "standup is Tuesday at 10")
- Makes a non-obvious decision worth recording
- Says "remember that", "save this", "log this", "add to memory", "note that"
- Finishes a meaningful working session future sessions should pick up
Write in third person about Bryan. Every note carries the canonical frontmatter (see below). Agent-generated notes set `agent_written: true`.
### Append to a file (default — additive entries)
Write content to a temp file first to handle multi-line markdown cleanly, then POST:
```bash
cat > /tmp/obs_entry.md << 'OBSEOF'
- 2026-06-02: <your entry here>
OBSEOF
curl -s -X POST \
-H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
-H "Content-Type: text/markdown" \
--data-binary @/tmp/obs_entry.md \
"https://goldbrainapi.mpm.to/vault/inbox/captures/inbox.md"
```
POST appends to the end of a file (creating it if absent). Use it for inbox captures, log sections, and daily-note Agent Log entries.
### Patch a specific heading (targeted update)
**Heading targets use the FULL heading path, `::`-delimited from the top-level heading** — a bare subheading name fails with `invalid-target`. For example, `## Fact / Pattern` under the `# Operator Preferences` H1 is targeted as `Operator Preferences::Fact / Pattern`. When unsure of the exact path, read the document map first (see below).
```bash
cat > /tmp/obs_patch.md << 'OBSEOF'
Bryan prefers status updates that lead with the decision.
OBSEOF
curl -s -X PATCH \
-H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
-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"
```
Use `Operation: replace` to overwrite a section entirely (e.g. a project's `Project Name::Current status`). Percent-encode non-ASCII characters in the `Target` header; spaces are fine.
**Discover exact heading paths** when unsure — GET the note with the document-map Accept header:
```bash
curl -s -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
-H "Accept: application/vnd.olrapi.document-map+json" \
"https://goldbrainapi.mpm.to/vault/_agent/memory/semantic/operator-preferences.md"
```
It returns `{ "headings": [...], "blocks": [...], "frontmatterFields": [...] }` — copy the heading string verbatim into `Target`.
### Create or overwrite a file (PUT)
```bash
cat > /tmp/obs_file.md << 'OBSEOF'
---
type: project
status: active
created: 2026-06-02
updated: 2026-06-02
tags: []
agent_written: true
source_notes: []
---
# Project Name
## Current status
...
## Related
- [[journal/daily/2026-06-02]]
OBSEOF
curl -s -X PUT \
-H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
-H "Content-Type: text/markdown" \
--data-binary @/tmp/obs_file.md \
"https://goldbrainapi.mpm.to/vault/projects/active/my-project.md"
```
The API creates intermediate directories automatically.
### Search the vault
```bash
curl -s -X POST \
-H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
"https://goldbrainapi.mpm.to/search/simple/?query=your+search+terms"
```
## Where to Write
| Situation | File / path | Method |
|-----------|-------------|--------|
| Unsure where it goes / quick capture | `_agent/.../` → use `inbox/captures/inbox.md` (date-prefixed line) | POST |
| Operator preference or durable fact | `_agent/memory/semantic/operator-preferences.md` (append under the right heading) | PATCH |
| Other durable facts / patterns | `_agent/memory/semantic/<slug>.md` | PUT |
| What happened (event record) | `_agent/memory/episodic/<slug>.md` | PUT |
| Short-lived working state | `_agent/memory/working/<slug>.md` | PUT |
| Task-scoped context / focus | `_agent/context/current-context.md` | PATCH / PUT |
| Working session ended with substance | `_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 into `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 |
Never delete files unless the operator explicitly asks. Memory is append-friendly; deletion is destructive.
## Session Logging
At the end of substantive conversations (ones that produced decisions, artifacts, or commitments), create a session log. Ask once if unsure: "Want me to log a session note for this?"
Session logs go in `_agent/sessions/YYYY-MM-DD-HHMM-<slug>.md`. See `references/session-log-template.md` for the exact format.
```bash
cat > /tmp/obs_session.md << 'OBSEOF'
<session log content — see references/session-log-template.md>
OBSEOF
curl -s -X PUT \
-H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
-H "Content-Type: text/markdown" \
--data-binary @/tmp/obs_session.md \
"https://goldbrainapi.mpm.to/vault/_agent/sessions/2026-06-02-1430-my-session.md"
```
Then append a one-line entry to the daily note's **Agent Log** section.
## Vault Unreachable
If the API returns a connection error, timeout, or `502`, tell the operator once that the memory vault is unreachable (a `502` usually means Obsidian/the REST plugin is not running on the backend), then proceed without memory. Do not retry repeatedly.
## Style Rules
- Write in third person about Bryan: "Bryan prefers X", not "I prefer X".
- Do not attribute Jason's design preferences to Bryan — capture Bryan's preferences only from observed interactions.
- Every memory file has canonical YAML frontmatter — see `references/vault-layout.md`.
- Set `agent_written: true` on agent-generated notes and list `source_notes` (plain relative paths, not links).
- **Never put `[[wikilinks]]` in frontmatter** — YAML parses them as nested lists and the links break in Obsidian's reading view. Put all cross-references in a `## Related` section in the note **body** as a bulleted list of `[[links]]`.
- Use Obsidian wiki links (`[[note name]]`) freely in the note **body** for cross-references.
- Keep entries short and focused. Fewer, sharper entries beat many noisy ones.
- About to write something large or sensitive? Show the operator the content first and confirm.
## What This Skill Does Not Do
- Does not replace reasoning. The vault is reference material — apply judgment.
- Does not auto-summarize the whole vault. Read targeted files, not everything.
- Does not store passwords or secrets, and never writes the API key into a vault note. If asked to "remember my password is X", decline and suggest a password manager.
.references/goldbrain-memory/skills/goldbrain-memory/references/api-reference.md
+207
View File
@@ -0,0 +1,207 @@
# 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 fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8`
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 fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
"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 fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
"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 fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
"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 fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
-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 fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
-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.
```bash
cat > /tmp/obs_patch.md << 'OBSEOF'
Bryan prefers concise status updates — lead with the decision.
OBSEOF
curl -s -X PATCH \
-H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
-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 fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
-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 fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
-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 fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
"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 fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
"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.
---
## 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/<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 (see `vault-layout.md`).
.references/goldbrain-memory/skills/goldbrain-memory/references/bootstrap.md
+37
View File
@@ -0,0 +1,37 @@
# Bootstrap Procedure
The goldbrain vault ships its **own** `BOOTSTRAP.md` at the vault root — that file is the canonical preflight/repair manifest. This plugin defers to it rather than duplicating the logic.
## Normal case — vault already bootstrapped
At session start, read the in-vault manifest:
```bash
curl -s \
-H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \
"https://goldbrainapi.mpm.to/vault/BOOTSTRAP.md"
```
If it returns content (200), the vault is set up. Skim its preflight checklist, then read `CLAUDE.md` for the operating contract and proceed with the loading procedure in `SKILL.md`. The in-vault `BOOTSTRAP.md` describes how to repair any missing folders/files; follow it if something is absent. **Never overwrite an existing file** during repair — generate only what is missing.
## Fresh-vault case — BOOTSTRAP.md returns 404
This means the REST API is pointed at an empty vault. Confirm with the operator once:
> "The goldbrain vault looks empty — there's no `BOOTSTRAP.md`. The standard scaffold (control docs, folder tree, templates, seed notes) needs to be loaded before I can use it as memory. Want me to create the core seed files now?"
If yes, create the minimum viable seed with `PUT` (the API creates intermediate directories automatically), then let the vault's own structure grow from there:
1. `CLAUDE.md` — operating contract and session protocol
2. `BOOTSTRAP.md` — preflight/repair manifest
3. `STRUCTURE.md` — layout, taxonomy, frontmatter standard
4. `index.md` — navigation hub
5. `_agent/memory/semantic/operator-preferences.md` — operator profile (empty, no fabricated facts)
6. `_agent/context/current-context.md` — empty context bundle
7. `inbox/captures/inbox.md` — capture file
Prefer copying the full prepared scaffold into the Obsidian vault folder over reconstructing it by hand — it is the source of truth for goldbrain's structure.
## After bootstrap
Tell the operator briefly what was created, append a line to the daily note's **Agent Log**, and write a session log in `_agent/sessions/`. Do not over-explain — they can browse the vault.
.references/goldbrain-memory/skills/goldbrain-memory/references/session-log-template.md
+108
View File
@@ -0,0 +1,108 @@
# Session Log Template
Session logs go in: `_agent/sessions/YYYY-MM-DD-HHMM-<slug>.md`
The slug describes what the session was about in 2–5 words, kebab-case.
Examples: `2026-06-02-1430-goldbrain-plugin-build.md`, `2026-05-14-0900-q1-review-prep.md`.
Keep logs focused. Capture the goal, what was read/done, decisions, outputs, open threads, and the next step. This matches the vault's `_agent/templates/session-log-template.md`.
---
## Template
```markdown
---
type: session-log
status: complete
created: 2026-06-02T14:30
updated: 2026-06-02T14:30
tags: [agent, session]
agent_written: true
source_notes: []
session_date: 2026-06-02
client: claude-code
---
# Session Log
## Goal
One line — what this session set out to do.
## Notes Read
- [[note]] — why it was relevant
(omit if none)
## Actions Taken
Brief narrative or bullets of what was done.
## Decisions Made
- Decision — why
(omit section if none)
## Outputs Created
- `path/or/filename` — what it is
(omit section if none)
## Open Threads
- [ ] unresolved question or next step
(omit section if none)
## Suggested Next Step
One sentence: what to do first next time on this topic.
## Related
- [[wikilinks go here, in the body — never in frontmatter]]
```
---
## Example
```markdown
---
type: session-log
status: complete
created: 2026-06-02T14:30
updated: 2026-06-02T14:30
tags: [agent, session, plugin]
agent_written: true
source_notes: ["resources/references/obsidian-local-rest-api.md"]
session_date: 2026-06-02
client: claude-code
---
# Session Log
## Goal
Build and package the goldbrain-memory CoWork plugin against the live vault.
## Notes Read
- [[BOOTSTRAP]], [[STRUCTURE]], [[_agent/memory/semantic/operator-preferences]]
## Actions Taken
Verified the REST API end-to-end, confirmed the scaffold copied into the live vault,
created missing empty folders, and built the plugin (SKILL + 4 reference files).
## Decisions Made
- Vault addressed at root (no `Projects/agents/` prefix) — goldbrain is a dedicated vault.
- Key hardcoded in the plugin (not in the vault) — personal plugin, per the reference pattern.
## Outputs Created
- `goldbrain-memory.plugin` — installable CoWork plugin
## Open Threads
- [ ] Validate Claude Code direct filesystem access to the vault host.
## Suggested Next Step
Install the plugin and run a live load/write through it to confirm the skill triggers.
## Related
- [[projects/active/vault-foundation]]
- [[resources/references/obsidian-local-rest-api]]
```
After writing the log, append a one-line entry to the daily note's **Agent Log** section.
> **Reminder:** wiki links go in the body (e.g. this `## Related` section), never in YAML
> frontmatter. `source_notes` in frontmatter holds plain relative path strings, not `[[links]]`.
.references/goldbrain-memory/skills/goldbrain-memory/references/vault-layout.md
+146
View File
@@ -0,0 +1,146 @@
# Vault Layout & Frontmatter Conventions
Mirrors the canonical conventions defined in the vault's own `STRUCTURE.md` and `BOOTSTRAP.md`. If those change, they are the source of truth.
## Folder Map (root-addressed)
```
/vault/
├── CLAUDE.md ← operating contract + session protocol
├── STRUCTURE.md ← layout, taxonomy, frontmatter standard
├── BOOTSTRAP.md ← preflight/repair manifest (read first)
├── spinup.md index.md README.md
├── inbox/
│ ├── captures/ ← quick captures (inbox.md), date-prefixed lines
│ ├── imports/ ← raw imported material
│ └── processing-log/
├── journal/
│ ├── daily/ ← YYYY-MM-DD.md (has an "Agent Log" section)
│ ├── weekly/ monthly/
│ └── templates/
├── projects/
│ ├── active/ ← <slug>.md, long-running project state
│ ├── incubating/ on-hold/ archived/
│ └── project-template.md
├── areas/ ← business / personal / learning / systems
├── resources/
│ ├── concepts/ references/ meetings/ source-material/
│ └── people/ ← <name>.md
├── decisions/
│ ├── by-date/ ← YYYY-MM-DD-<slug>.md (ADR-style)
│ ├── by-project/ ← mirror by project
│ └── decision-template.md
├── reviews/ ← weekly / monthly / quarterly / annual
├── archive/ ← notes / projects / imports
└── _agent/
├── context/ ← current-context.md and task bundles
├── memory/
│ ├── working/ ← transient, time-boxed
│ ├── episodic/ ← what happened, when
│ └── semantic/ ← durable facts/patterns (operator-preferences.md)
├── sessions/ ← YYYY-MM-DD-HHMM-<slug>.md
├── templates/ ← canonical note templates
├── outputs/ ← briefs / drafts / summaries / synthesis
├── skills/ ← active / archived
└── heartbeat/
```
**Slug rules:** kebab-case, ASCII only, truncate to ~40 chars.
---
## Canonical Frontmatter
Every note starts with this block. Fill what applies; leave the rest empty rather than guessing.
```yaml
---
type: # see Note Types below
status: # active | draft | done | archived | complete
created: # YYYY-MM-DD (or YYYY-MM-DDTHH:mm for sessions)
updated: # YYYY-MM-DD
tags: []
agent_written: false
source_notes: [] # plain relative paths as strings — NEVER [[wikilinks]]
---
```
`agent_written: true` + a populated `source_notes` is the key signal separating
agent-managed content from human-authored content. When appending with POST, do
not rewrite frontmatter — the append goes after existing content. To change
`updated:` or `status:`, use PATCH with `Target-Type: frontmatter`.
> **No `[[wikilinks]]` in frontmatter.** YAML parses `[[...]]` as nested lists, so wiki
> links there break and never render as clickable links in reading view. Put all
> cross-references in a **`## Related`** section in the note **body** (bulleted `[[links]]`).
> Frontmatter holds scalar/string metadata only; `source_notes` values are plain relative
> paths, not links.
## Note Types
`daily-note`, `weekly-note`, `monthly-note`, `project`, `project-update`, `area`,
`concept`, `reference`, `person`, `meeting`, `decision`, `review`, `session-log`,
`working-memory`, `episodic-memory`, `semantic-memory`, `context-bundle`, `skill`,
`draft`, `inbox-item`.
---
## File-Specific Conventions
### operator-preferences.md (`_agent/memory/semantic/`)
The profile analog. Headings include `Operator`, `Fact / Pattern`, `Evidence`,
`Recommendation or Implication`, `Review Notes`. Append observed facts under the
right heading via PATCH. "The operator" is Bryan; do not attribute Jason's design
preferences to Bryan without evidence.
### projects/active/\<slug\>.md
```markdown
---
type: project
status: active
created: 2026-06-02
updated: 2026-06-02
tags: []
agent_written: false
source_notes: []
---
# Project Name
## Current status
One paragraph, kept fresh via PATCH replace.
## Decisions
- [[YYYY-MM-DD-decision-slug]] — one-line summary
## Open threads
- [ ] unresolved thing
## Log
- 2026-06-02: observation or update
## Related
- [[areas/business/business-ops]]
```
### sessions/YYYY-MM-DD-HHMM-\<slug\>.md
See `session-log-template.md`. Note goldbrain uses an **HHMM time component** in the
filename (unlike a date-only convention).
### decisions/by-date/YYYY-MM-DD-\<slug\>.md
ADR-style: Context → Decision → Consequences. Mirror a link into `by-project/`.
### people/\<name\>.md
`type: person`. Use lowercase kebab-case for the slug (e.g. `bryan-gilliom.md`).
---
## Cross-References
Use Obsidian wiki links freely: `[[note-name]]` or `[[folder/note]]`. The REST API
doesn't resolve them, but Obsidian does when the operator browses the vault.