brain-sync

name	brain-sync
description	Load and navigate a structured second brain managed by brain-sync. Use this skill whenever the user mentions "brain", "second brain", or asks about topics, initiatives, people, or context tracked in their brain. Also trigger when asked to set up syncing for a URL. Trigger liberally. If in doubt, load the brain.

brain-sync — Second Brain Skill

A structured second brain with knowledge/ for human and synced content, plus co-located managed summaries under knowledge/**/.brain-sync/insights/. All interaction goes through brain-sync MCP tools. An "area" is a folder under knowledge/. Each area can have a managed summary.md at knowledge/<area>/.brain-sync/insights/summary.md that acts as the area's landing page.

Typical workflow

1. brain_sync_get_context() or brain_sync_tree() — load broad orientation.
2. brain_sync_query("search terms") — find matching areas. If the response says areas_truncated=true, call brain_sync_list_areas(filter=...) to find exact paths beyond the query sidebar.
3. brain_sync_open_area("path") — read the summary and insight artifacts.
4. brain_sync_open_file("path") — only if insights don't answer the question.

Always read the area's summary via brain_sync_open_area() before opening raw source files. Only call brain_sync_open_file() when the summary and insight artifacts do not answer the question. Stop once the question can be answered.

MCP Tools

Querying the brain

Tool	Purpose
brain_sync_tree	Return the full semantic knowledge-area tree with sparse structural metadata. Use for whole-brain structure, file mix, insight coverage, and synced-source state overview.
brain_sync_query	Start here. Search for areas matching a query. If additional context is needed, call brain_sync_get_context().
brain_sync_list_areas	List area paths with optional path filtering and pagination. Use when query/context area lists are truncated or when you need an exact path.
brain_sync_get_context	Load global context from knowledge/_core/.brain-sync/insights/summary.md for broad orientation.
brain_sync_open_area	Drill into a specific area — full summary, insight artifacts, children.
brain_sync_open_file	Read a specific file when insights aren't enough. Supports offset for pagination (default 16k chars/call).

Managing sync sources

Tool	Purpose
brain_sync_list	List registered sources (optional filter_path).
brain_sync_suggest_placement	Suggest placement areas for a new document. Always present results to the user.
brain_sync_add	Register a URL for syncing (source, target_path, optional flags).
brain_sync_add_file	Add a local .md or .txt file to knowledge/ (source, target_path, copy).
brain_sync_sync	Request immediate polling for active sources (sources, omit to target all active sources).
brain_sync_update	Update settings for a source — pass only the flags to change (fetch_children, sync_attachments, child_path).
brain_sync_remove	Unregister a sync source (source = canonical ID or URL).
brain_sync_remove_file	Remove a local file from knowledge/ (path relative to knowledge/).
brain_sync_move	Move a source to a new path (source, to_path).
brain_sync_regen	Regenerate insights (optional path, omit for all).

All tools return {"status": "ok", ...} on success or {"status": "error", "error": "<type>", ...} on failure.

When to use which tool

• First interaction with the brain: call brain_sync_get_context() to load global context (distilled _core meaning such as taxonomy, terminology, org structure) before querying.
• Need a whole-brain structural snapshot: call brain_sync_tree() before drilling in.
• Know what you're looking for: brain_sync_query("search terms") → review matches → brain_sync_open_area("path").
• Need an exact area path in a large brain: call brain_sync_list_areas(filter="name fragment"); use offset when the response includes next_offset.
• Need background understanding: brain_sync_get_context() for broad orientation without a specific search.
• Need to inspect area shape or stale/missing synced sources: brain_sync_tree() to see the semantic tree, direct file counts, insight coverage, journal coverage, and synced-source lifecycle counts before opening a specific area.
• Deep dive into source material: brain_sync_open_file("knowledge/path/file.md") — only when insights don't answer the question.
• Need raw _core source material: brain_sync_open_file("knowledge/_core/<file>") rather than relying on global context, which is summary-only.
• User wants to sync a URL: brain_sync_add(url=..., target_path=...).
• User wants an existing source checked now: brain_sync_sync(sources=[...]) or omit sources to request all active sources.

Access rules

• Read knowledge/ content and managed summaries via MCP tools
• Read managed summaries via .brain-sync/insights/ and journals via .brain-sync/journal/
• Do not write to managed .brain-sync/ files — they are regenerated by brain-sync when knowledge changes
• May manage sync sources when the user asks

Adding content to the brain

When the user asks to "sync", "add", or "track" a URL or file:

Step 1 — Suggest placement

Unless the user has already specified a target path, call brain_sync_suggest_placement with the document title (and excerpt if available). Always present the returned candidates to the user as a numbered list with paths and reasoning. Let the user choose or provide a custom path. Never auto-select.

Step 2 — Add the source

Call the appropriate tool with the user's chosen target_path:

• URLs: call brain_sync_add with source (the URL) and target_path. Optional flags: fetch_children, sync_attachments, child_path.
• Files: save to a temp file, then call brain_sync_add_file with the file path as source, target_path, and copy=true.

Use $ARGUMENTS as a hint for which area to query (e.g. invoked with "AAA", search for the matching initiative). Otherwise infer from conversation context.