ybrain

ybrain — Personal Exobrain Methodology Layer

Manage your personal exobrain on IMA with the CODE loop (Capture→Organize→Distill→Express) + PARA organization method. This skill is self-contained: all terminology, rules and API documentation needed for operation are in this file and in scripts/、references/ ; the design consensus documents (GLOSSARY, ADR) are kept in the development repository as background only and need not be read at runtime.

Positioning and Hard Boundaries

• This skill isfully self-contained: methodology (this file) + transport and tool scripts (scripts/) + API documentation (references/), with no dependency on ima-skills or any external skill.
• Transport uniformly goes through node "$SKILL_DIR/scripts/ima_api.cjs" <apiPath> <json-body>（$SKILL_DIR = this skill's directory; credentials are automatically read from ~/.config/ima ). ⛔ It is forbidden to bypass it and directly construct IMA requests with curl.
• All API documentation is built in; read the corresponding file before calling：
  • General rules (UTF-8 validation, file upload security gate, error codes, URL type detection, get_media_info, MediaType and size limits) → references/core-rules.md
  • Knowledge base extension surface (create base/create folder/move/rename/tags/browse/locate) → references/knowledge-base-{read,write,upload,tag}.md
  • Note surface (read/write/block editing/notebook management/export) → references/notes.md(for the full set of structs and error codes see its notes-api.md）
• First-use guidance and best practices → references/best-practices.md: required reading during Bootstrap, when each workflow is completed for the first time, and when the user asks "how do I use this skill/what is it for/how do I start"; guide them according to its "five-step experience loop"
• Deletion still does not exist: knowledge base entries, folders, notes, and notebooks cannot be deleted. Any entry judged "non-existent" is uniformly moved to 4-存档; when the user insists on deletion, tell them to do it manually in the IMA client, and do not construct or retry deletion interfaces.
• export_media_for_ima_sandbox The current credentials have no permission (220030), use is prohibited; for knowledge base entry original text use the get_media_info branch (references/core-rules.md), for note original text use export_note。
• Write operations are irreversible. Writes within the scope of explicit user instructions ("note this down", repositioning confirmed after "organize inbox") are executed directly; writes outside that scope (creating new knowledge packages, renaming, tag_delete / tag_rename, etc.) must be confirmed first.
• Stop immediately when credentials are missing: if an IMA call reports "IMA credentials not found" (-100) → stop subsequent calls, do not retry, guide the user to https://ima.qq.com/agent-interface to obtain clientId / apiKey, assist in writing ~/.config/ima/client_id and ~/.config/ima/api_key(or set IMA_OPENAPI_CLIENTID / IMA_OPENAPI_APIKEY), and once ready continue from the interrupted step.
• Before operating on a knowledge base use search_knowledge_base to confirm the role is creator/collaborator/administrator; reject write operations on the knowledge bases of ordinary members.

Information Architecture (Dual-layer Single-base System)

Layer	Carrier	Content	Nature
Memory layer	Knowledge base "ybrain"	Raw materials: web pages, files, external content	Entry-based, traced back via folders + search
Thought layer	Notebook "ybrain"	Knowledge package: refined output	Continuously appended living document

• The knowledge base has exactly five top-level folders:0-收件箱 / 1-项目 / 2-领域 / 3-资源 / 4-存档
• Dual-channel capture: external materials (links / files / mobile) → knowledge base 0-收件箱; text inspiration → notebook "0-Inbox" note
• Title prefix convention: knowledge package 【项目】X / 【领域】X; expression output 【输出】X; archived knowledge package 【归档】X

ID resolution and Bootstrap (executed once per session, then reused)

1. search_knowledge_base(query="ybrain") → knowledge base ID (also record role_type)
2. get_knowledge_list(root directory) → IDs of the five top-level folders
3. list_notebook → the folder_id of the notebook "ybrain"
4. search_note(title "0-Inbox") → the note_id of the inspiration inbox note
5. If any is missing → execute Bootstrap: show the checklist below to the user,confirm oncethen execute consecutively, filling in whichever step is missing and skipping the ones that already exist:
   • create_knowledge_base(name="ybrain", type=1001 personal library)
   • create_folder × 5：0-收件箱、1-项目、2-领域、3-资源、4-存档
   • add_notebook（folder_name="ybrain"）
   • import_doc create the "0-Inbox" note in that notebook
6. When Bootstrap is complete: according to references/best-practices.md explain to the user in one sentence what was created and why it is a two-layer structure, and guide them through their first capture

Intent routing table

User says	Workflow
"Note this down / save this / bookmark this / capture"	Capture
"Organize the inbox"	Organize
"Project X is finished / archive"	Organize (archive branch)
"Refine this article / turn X into a note / distill"	Refine
"Help me write / draft / produce a piece"	Express
"The X I saved before / is it in the exobrain / how do I look at Y in the materials I saved"	Recall
"What can you do / how do I use this skill / how do I get started"	Read references/best-practices.md guide
General IMA operations with no methodology context (e.g. "upload this file to the paper library")	Can be executed directly using this skill's built-in transfer (references/ is the complete API documentation)

Command entry points (companion skills)

This skill can be installed on its own; during a full installation, four command skills are installed at the same time as shortcut entry points for high-frequency workflows:

Command skill	Workflow
ybrain-capture	Capture
ybrain-organize	Organize (organize inbox / project archive)
ybrain-distill	Refine
ybrain-express	Express

Slash syntax follows the hosting agent (e.g. /ybrain-capture, $ybrain-capture, OpenCode's @ybrain-capture). Command skills are thin entry points to this skill, installed in the same directory as this file, and depend on this skill's scripts/ and references/ at runtime; if the two descriptions differ, this file prevails.

Capture

Principles:Do not ask about classification, do not interrupt flow; capture first, classify later. During the capture phase, the four-question filter is prohibited.

Automatically route by content type, no confirmation needed:

Content	Destination	Method
Webpage/WeChat official account link	Knowledge base 0-收件箱	import_urls Direct import
Files (local or file-type URLs)	Knowledge base 0-收件箱	Built-in file upload safety gate (references/core-rules.md)
Text inspiration	Notes in the "0-Inbox" notebook	append_doc, one per line, with an optional one-sentence note

Probe the remote first for local path references: When a local directory/file path is to be recorded as a reference (e.g., "note down the xx skills directory"), the local path is unreachable across devices, so before writing it down, probe the git remote once:

1. git -C <路径> remote get-url origin Success → convert to a remote web link record:https://<host>/<owner>/<repo>/tree/<branch>/<仓库内相对路径>(strip the .git suffix;user@host:path forms are first converted to https://<host>/; for branches use git branch --show-current to retrieve, and if unavailable, stop at the repository name)
2. Not a git repository or no remote → record the path as-is, do not retry, do not ask further, do not block the capture

When the conversion succeeds, state in the reply that it has been replaced with a remote link. This also applies when annotating local source paths in knowledge packages and in【Output】notes.

Organize

Tidy the inbox (trigger: "tidy the inbox")

1. Gather:get_knowledge_list（0-收件箱) to list external materials + export_note to read inspiration entries in the "0-Inbox" notebook.
2. First list the current project inventory (1-项目 subfolders + 【项目】 knowledge package titles), then filter each entry with the four questions and give a suggestion: Which project is this useful for? → If none, which area is it useful for? → If none, which resource does it belong to? → If none of these, archive it, or do not save it.
3. Output a suggestion table to the user for confirmation (including a "do not save" option).
4. Placement (fully automatic)：
   • External materials → move_knowledge move into the target folder (at most 10 each time, in batches; check each one ret_code, list failures in the report)
   • Inspiration → append to the corresponding knowledge package (it is done once appended); if there is no corresponding knowledge package and it is not worth creating a new one → keep it in the inbox note
   • "Do not save" → move_knowledge move into 4-存档
5. Inspiration cleanup:export_note_blocks locate the processed entry block → update_note(action=2 DELETE) remove;user_request_id reuse the same UUID within this round of tidying.
6. Ask one closing question: which entries should be distilled along the way? → switch to the distillation workflow.

Project archive (trigger: "project X is finished")

Execute fully automatically, then report counts when done:

1. get_knowledge_list（1-项目/X) list all files
2. create_folder（4-存档/X）
3. move_knowledge move in batches (the folder itself cannot be moved: after the contents are moved, the empty shell remains; inform the user that it can be deleted on the client side)
4. Knowledge package rename_note：【项目】X → 【归档】X, keep for reference

Distill

1. Get the original text: for knowledge base entries use the get_media_info branch (references/core-rules.md); for notes use export_note(target_content_format=1, download content_url to get Markdown); for external web pages use WebFetch.
2. Distill into structured key points; you may ask the user one question, "Is there any resonance or thought you want to note down?" (optional, not mandatory — knowledge base entries cannot have annotations, and resonance can only be noted in notes during distillation).
3. Locate the knowledge package:search_note title 【项目】X or 【领域】X. If it exists → after confirming with the user, append_doc append a new section (to revise an old section use export_note_blocks + update_note); if it does not exist → after confirming the title and prefix with the user, import_doc create a new one.
4. Short-focus annotation: at the end of a new chapter, annotate "Available for: Project X / None for now", to gather material for long-focus projects.

Express

1. Material gathering:search_knowledge(memory layer + sealed volume) + search_note(thought layer + sealed volume) → output material list → user confirms scope.
2. Draft, then self-check with a Feynman review: can someone who only understands the basic concepts understand this passage? Where are the sticking points that are still not explained clearly? → revise.
3. The finished product is stored as 【输出】标题 import_doc in the notebook ybrain (split super-long content across multiple append_doc, over-limit signal 210009, see references/core-rules.md; do not use the COS long-content path), and display the full text in the session for the user to copy and publish.

Recall

search_knowledge + search_note two-sided retrieval (memory layer, thought layer, sealed volume) → when the original text needs to be read: knowledge base entries go through get_media_info, notes go through export_note → synthesize an answer → annotate sources (entry title / the library or notebook it is in), without exposing internal IDs.

Sealed volume (treated as a resource, participates in retrieval, not migrated in)

The existing knowledge bases and notebooks in the user's account other than ybrain are collectively called the sealed volume: not migrated, not reorganized, and only participate in retrieval as background resources during recall and expression.

• Old notebooks: no configuration needed,search_note is globally searchable and naturally covered;
• Old knowledge bases: when needed for the first recall/expression, use search_knowledge_base(pass an empty string as query to list all knowledge bases) to lazily enumerate; the libraries other than ybrain are the sealed volume, parse their IDs one by one and reuse them within the session.

The user may explicitly name certain libraries to exclude (such as shared libraries maintained by others); when retrieval results do not match expectations, ask the user to confirm the list of old libraries included in retrieval.

Common mistakes

Mistake	Correction
During capture, asking "which project/domain does this go in"	Capture does not ask about classification; everything goes into the inbox; the four-question screening is only done when "organizing the inbox"
Trying to call an API to delete an entry, or retrying repeatedly	There is no delete API; entries judged "do not store" are moved to 4-存档, deletion can only be done manually on the client
Trying to use export_media_for_ima_sandbox to get the original text	220030 no permission; use get_media_info(entries) or export_note(notes)
Link capture first recorded into notes, then imported during organizing	Links directly import_urls into 0-收件箱; the note inbox only collects text inspiration
Recording a local path directly as a long-term reference	Local paths are unreachable across devices; first git -C <路径> remote get-url origin probe; if there is a remote one, convert it to a web link; if not, keep it as is
Generating a "manual drag-and-drop checklist" for the user	Placing back/archiving is fully automatic:move_knowledge / rename_note / update_note
Using a "organized" marker to divide inbox notes	Deprecated; processed inspiration is deleted with the update_note block
Creating a new knowledge pack for each extraction	Keep appending to the same one for the same project/topic, distilling and adding value
After expression, only displaying in the session	The finished product must be saved to disk as a 【输出】 note; only with an output trace can it flow back as material
Show internal IDs such as kb_id / note_id to the user	Show only names
After credentials are missing, repeatedly retry the call and only paste the error	Stop calling, guide the user to https://ima.qq.com/agent-interface to obtain credentials and assist with configuration (see hard boundaries)
Bypass scripts/ima_api.cjs and directly curl the IMA interface	All transmission goes through the built-in ima_api.cjs, with credentials and errors reused in layers
Sync updates from ima-skills to overwrite the built-in script	The built-in copy is intentionally frozen (ADR-0004); upstream fixes require manual re-vendoring while preserving local patches