Platform mechanics: Apps use @joshu/platform-data (files.query, files.getPage, memory.recall). Agents use gbrain MCP tools below. This skill covers retrieval workflow — not REST/MCP wiring.

When to Use

Mail / email (find, search, recall, send): Load skill joshu-mail — not this skill. gbrain is step 1 inside joshu-mail, but Composio workbench, multi-account routing, and send rules live there.

Use gbrain (read-only MCP tools from the gbrain server) when the user asks about:

Files on their Desktop (including joshu's files)
Journals, research notes, uploads, PDF extracts / .txt wraps (sibling .md next to source files), or anything saved as files
"What did I write about X?" when the answer should come from documents

Use Hindsight memory (Hermes memory provider) when the user asks about:

Conversation history: "weren't we talking about X?"
Preferences and facts from past chats
Rambling recall without a specific file

Do not duplicate chats into markdown files for gbrain. Hindsight owns conversational memory.

Finding user self-sent notes & reminders

When the user says "I sent some notes/reminders via email" or "remember those random things I jotted down":

gbrain_query first — the mirrored email content is already indexed. Semantic search catches notes even without exact subject keywords.
Gmail API second — only if gbrain misses something.

Common subject patterns on user notes: "Another note to file", "Another idea to jot down", "Top things to sort out", or blank. More detail in references/find-user-notes.md.

Brain-first retrieval

For file/knowledge questions on the user's Desktop (any folder), call gbrain query with:
- query: the user's question or keywords
- source_id: "__all__" (cross-source; required for files outside joshu's files)
- limit: 10–20
- recency: "on" and since: "90d" (or "30d", "7d") for recent mail/journal questions — Joshu MCP normalizes these to ISO timestamps before SQL
Do not rely on MCP search alone for Desktop-wide lookup — search is keyword FTS on the default source (joshu's files / journals) and often returns empty for federated paths like investors/… or joshus-files/workspace/….
Cite results with the slug from gbrain (lowercase; may not match on-disk folder casing).
Use chunk_text from query results when get_page returns page_not_found for a federated slug.
Use hermes-cli / search_files (ripgrep) on disk only when gbrain returns nothing relevant.

MCP server URL (Joshu-supervised): http://127.0.0.1:8794/mcp — one shared gbrain serve process; do not spawn a second gbrain.

Writing structured files (critical)

Do not use gbrain write tools (put_page, delete, sync_brain, schema tools, etc.). They are not available on the Joshu MCP surface.

All user-visible files must land on disk under JOSHU_FILES_ROOT (the joshu's files folder on ArozOS Desktop) — never macOS ~/Desktop and never Desktop/journals/ at the Desktop root.

Read JOSHU_FILES_ROOT from the environment (absolute path). Joshu sets this to the sandbox owner’s ArozOS Desktop tree (joshu's files), not a path you invent in chat.
If unset, read LOCATION.md inside that folder.
Do not write to ~/Desktop, paths outside JOSHU_FILES_ROOT, or sibling folders on Desktop.

Layout under JOSHU_FILES_ROOT:

FILING.md
Planning/                      # capture-*, daily-review-*, time-block diagrams (one .excalidraw per day)
Triage/                          # work queue stubs → connector threads (mail only)
Projects/<slug>/                 # about.md, todo.md, journal_YYYY-MM-DD.md
connectors/mail/nylas/threads/              # agent inbox (Nylas)
connectors/mail/gmail/{account_key}/threads/  # principal Gmail (Composio, per account)
connectors/calendar/
connectors/_state/                          # sync cursors (machine)
journals/                        # optional personal capture (non-EA)
research/                        # notes and investigation
inbox/
uploads/

PDF text extraction

Users can drop text PDFs anywhere on the ArozOS Desktop (JOSHU_DESKTOP_ROOT), including folders outside joshu's files. Joshu auto-extracts a sibling .md next to the PDF (report.pdf → report.md; if that name is taken, report.pdf.md). The PDF stays in place. When the PDF bytes change, the sidecar is re-extracted; deleting the PDF removes the sidecar. No agent action required.

Do not paste full PDF bodies into markdown — the ingest pipeline handles extraction.
Scanned/image PDFs may fail ingest; suggest OCR or manual markdown if extraction errors.
File Brain shows an activity pill while extract/reindex is running.

Plain text (.txt)

Users can drop .txt files anywhere on the Desktop the same way. Joshu wraps them to a sibling .md (notes.txt → notes.md; if taken, notes.txt.md). The .txt stays in place. gbrain sync still only imports markdown — the wrap is what makes text files searchable.

Read FILING.md and docs/executive-assistant.md#gtd-workspace before creating new pages. Connector layout and APIs: Joshu docs/connectors.md. PDF / TXT ingest details: docs/file-brain.md.

Linking for recall (EA projects)

When writing or editing project markdown, link — do not duplicate mail bodies:

[subject](joshu://connectors/mail/…/threads/<id>.md) or relative ../connectors/mail/…
gbrain sync extracts links and [[wikilinks]] → use get_backlinks / traverse_graph to find related pages
Chat capture lives in Planning/capture-*.md first; Hindsight holds conversation — do not dump chat logs into files for gbrain

Filesystem writes (only write path)

Write or edit markdown with Hermes filesystem tools at absolute paths, e.g.:

${JOSHU_FILES_ROOT}/journals/2026-05-24-slug.md

Correct path	Wrong
`${JOSHU_FILES_ROOT}/journals/2026-05-24-todo.md`	`~/Desktop/...`
`${JOSHU_FILES_ROOT}/research/my-topic.md`	`${JOSHU_FILES_ROOT}/joshu's files/journals/...` (double-nested)
`${JOSHU_FILES_ROOT}/journals/...`	`Desktop/journals/...` at ArozOS Desktop root

Path is identity — journals/ → journal type, research/ → research, etc. after gbrain indexes the file (automatic, ~few seconds).
Prefer .md in journals/research/inbox (gbrain sync imports .md/.mdx by default).
Optional YAML frontmatter (type, date) should match the folder; gbrain classifies primarily by path prefix.

Before creating a new journal, list journals/ (filesystem or gbrain query with source_id: "__all__" and a journal keyword) and update the existing file instead of duplicating topics.

Full Desktop (shortcuts, other folders) is indexed via a federated gbrain source registered at boot; writes stay under JOSHU_FILES_ROOT only.

Joshu API (optional)

When MCP is unavailable, the Joshu server on :8788 exposes read-only routes (same cross-source behavior when MCP HTTP on :8794 is up):

GET /joshu/api/brain/search?q=...
GET /joshu/api/brain/query?q=...