db-aeon/joshu-oss/joshu-brain

Joshu File Brain

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 (multi-channel)

When the user says "I sent some notes/reminders via email" or "remember those random things I jotted down" — or sends a note via Slack DM:

1. gbrain_query first — the mirrored email content is already indexed. Semantic search catches notes even without exact subject keywords.
2. Gmail API second — only if gbrain misses something.
3. Cross-channel dedup — if the same note arrives via Slack that was already tracked from email, write a journal entry with (re-up) rather than duplicating the todo item. See `references/find-user-notes.md`.

Common subject patterns on user notes: "Another note to file", "Another idea to jot down", "Top things to sort out", or blank.

Filing user product notes & ideas

When the owner sends a product idea/note (email, Slack, voice), load `references/file-product-notes.md` for the complete filing workflow: target project selection, journal create/append, about.md updates (Design Concepts / Active threads), and memory backup.

The pattern: one journal entry per date, about.md as the living reference, and memory for cross-session recall. Do not create task-actionable items in todo.md for conceptual ideas — those go into Design Concepts. If the idea implies concrete next steps, add a todo row and the Design Concepts entry.

Brain-first retrieval

1. 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

1. Do not rely on MCP `search` alone for Desktop-wide lookup — search is keyword-only FTS and misses paraphrased matches that query (hybrid semantic + keyword) finds.
2. Cite results with the slug from gbrain (lowercase; may not match on-disk folder casing).
3. Use chunk_text from query results when get_page returns page_not_found for a slug.
4. 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.

1. 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.
2. If unset, read `LOCATION.md` inside that folder.
3. 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

• 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 in the single default gbrain source; 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=...