hylo-compile-note · diff
git:20261019.46864aa to git:20261020.62f8435
50 added, 76 removed. Audit A to A.
---
name: hylo-compile-note
description: "Compiles one raw note into knowledge units under /_knowledge/ (triage, then create or update each unit). Use when the user wants a note compiled or turned into knowledge ('compile this note', '编译这篇笔记'), or when a compile trigger runs."
---
# Hylo Compile Note
- Compiles a single raw note into **knowledge units** — wiki-style pages that capture the author's accumulating understanding of the entities and concepts that matter to them.
-
- Calls below are Hylo's MCP tools (server `hylo`); your client may show them prefixed, e.g. `mcp__hylo__read`. If they are not in your tool list, search your deferred tools for "hylo".
-
- **Run all five steps to completion without stopping.** Do not present intermediate results, ask for confirmation, or pause between steps. Pre-compile (Step 3) is internal — never output it to the user. Only speak at the end (Step 5 summary).
-
- ---
+ Compiles one raw note into **knowledge units**: wiki-style pages holding the author's growing understanding of the entities that matter to them.
- ## Inputs
+ Tools named here are Hylo's MCP tools (server `hylo`, maybe shown as `mcp__hylo__read`). If they aren't in your tool list, search your deferred tools for "hylo"; if still missing, say Hylo's tools are unavailable and stop.
- 1. **Note path** — the raw note to compile (vault-absolute or filesystem path)
- 2. **Knowledge directory** — where knowledge units live (default: `_knowledge/` relative to cwd, which is always the vault root)
+ **Run all four steps without stopping**: no intermediate results, confirmations or pauses. Speak only at the end of Step 4.
- ---
+ The input is the note to compile (a vault-absolute or filesystem path). Units live in `/_knowledge/`.
## Step 1 — Read the note
- Read the full content of the target note. Note its path and **original publication date** — check in order: YAML front matter (`date` / `published`), filename date prefix, article/podcast header, or any explicit timestamp in the body. Record this as `source_date`. If none is found, mark `source_date` as unknown.
-
- Also record whose words the note holds, as `source_perspective`:
-
- - `own` — the author's own writing: short notes, journal, drafts, notes on their own projects or work, their own podcast or product.
- - `external` — what someone else wrote or said: clipped articles, transcripts of other people's podcasts or talks, book excerpts.
-
- Judge by the content, not only the folder; a clip with long comments of the author's own is still `external` unless the comments carry the note.
-
- ---
-
- ## Step 2 — Load relevant knowledge index
-
- List available domain indexes with `knowledge_list_indexes`. It returns `indexes`, a list of `{"domain": "...", "path": "..."}` objects. Based on the note's content, select the 1–2 domains most relevant to what the note covers. Read only those index files to obtain the unit table for this compilation.
+ Read it in full. Record:
- If the output is empty (no indexes exist), fall back to cold start: scan `<knowledge-dir>` directly and build a compact table (title | entity_type | tags | first paragraph ≤80 chars).
+ - `source_date`, its **original publication date**, from the first of: frontmatter `date` / `published`, a date prefix in the filename, an article or podcast header, a timestamp in the body. None found: unknown.
+ - `source_perspective`, whose words it holds. `own`: the author's writing (short notes, journal, drafts, notes on their own projects, their own podcast or product). `external`: someone else's (clipped articles, transcripts of others' podcasts or talks, book excerpts). Judge by content, not folder; a clip with the author's comments stays `external` unless the comments carry the note.
- ---
+ ## Step 2 — Load the relevant index
- ## Step 3 — Pre-compile (internal, not shown to user)
+ `knowledge_list_indexes`, pick the 1–2 domains closest to the note, and read only those indexes for their unit tables. No indexes: `knowledge_list {"kind": "knowledge"}` and build a compact table yourself (title | entity_type | tags | first paragraph, ≤80 chars).
- Scan the note and produce a **unit manifest** — a list of knowledge units to create or update. Do not generate any content yet.
+ ## Step 3 — Pre-compile (internal, never shown)
- ### What qualifies as a knowledge unit
+ List the units to create or update, without writing content yet.
- A knowledge unit is a wiki page for any **core or key entity** in the note that has depth worth accumulating. There are no fixed types — an entity can be a person, company, book, concept, technique, place, event, story, product, methodology, or anything the note treats with substance.
+ A unit is a wiki page for a **key entity** the note treats with substance: a person, company, book, concept, technique, place, event, product, method, anything. It qualifies only if all three hold; otherwise fold the content into another unit:
- ### Three qualifying questions
+ 1. **A stable name**: a recognized term or proper noun, not a sentence ("the argument that…").
+ 2. **Depth to accumulate**: mechanisms, tensions, implications, not just a definition. One clear defining sentence, and more to say beyond it.
+ 3. **It will recur** across notes from different contexts and dates.
- Before adding a unit to the manifest, answer all three:
+ Calibrate:
- 1. **Does it have a stable name?** A recognized term or proper noun — not a sentence ("the argument that..."). Unnamed ideas belong inside another unit.
- 2. **Does it have depth to accumulate?** If the content would just restate a definition, there's nothing to compile. A unit needs room to grow — mechanisms, tensions, implications, meaning.
- 3. **Will it recur?** Would this entity appear across notes from different contexts and dates? If yes, it belongs here. One-off references don't.
+ - **Too broad**: the title is a domain ("AI Trends"). Find the specific entity the note advances.
+ - **Too narrow**: a sub-point, data point, metric, dependent sub-argument or passing mention. Fold it in.
+ - **Two units or one**: split when they have different cores that would grow independently; keep one as a sub-point when it's an example or implication of the other.
- If any answer is no, fold the content into an existing unit instead.
+ Manifest (may be empty):
- ### Granularity calibration
+ | unit name | entity_type | operation |
+ | --- | --- | --- |
+ | <unit title> | <freeform> | create |
+ | <unit title> | <freeform> | update |
- **Too broad** — the title is a domain, not an entity ("AI Trends"). Fix: find the specific entity the note actually advances.
+ `entity_type` is a short freeform label (`person`, `company`, `book`, `concept`, `event`, `technique`…), with no templates tied to it. Before Step 4, read the file of every `update` unit at `/_knowledge/<unit-name>.md`.
- **Too narrow** — a sub-point or isolated fact with no room to grow. Fix: fold into the relevant unit.
+ ## Step 4 — Compile
- **Right size** — something you'd naturally treat as its own subject. One clear defining sentence, and more to say beyond it.
+ Each unit follows *Unit format* below plus its operation's file: `references/create.md` or `references/update.md`. Finish one unit before the next. Then say which were created, which updated, and what changed in each.
- ### Split vs. sub-point
+ ## Language
- Create two units when they have **different cores** and would grow independently. Keep as a sub-point when one is an example or implication of the other — separating them would leave both thin.
+ Match the language of the existing units, or of the note when there are none; section names follow it (`## 来源`). Dates are `YYYY-MM-DD`.
- ### Don't add to the manifest
+ ## Time
- - Data points and metrics
- - Sub-arguments that don't stand alone
- - Passing references with no analysis
+ Anchor time to the source's **original date**, not the compile date: write "as of <source_date>" for anything time-sensitive. When `source_date` is unknown, leave the time out or say "date unknown"; never use today's date.
- ### Output: unit manifest
+ ## Unit format
- | unit name | entity_type | operation |
- | -------------- | ------------ | --------- |
- | \<unit title\> | \<freeform\> | create |
- | \<unit title\> | \<freeform\> | update |
+ **Content.** Choose and name sections freely; let the entity dictate the structure (a person, a book, a company and a technique each call for different organization). Ask what the author needs to know about it when they return later. A unit holds only what's most important: source notes are the permanent record, the unit is a living distillation.
- `entity_type` is a short descriptive label for what this entity is (e.g. `person`, `company`, `book`, `concept`, `event`, `technique`). It is freeform metadata — there are no type restrictions and no templates tied to it.
+ **Two required sections:**
- The manifest may be empty if the note has no content worth compiling. Immediately continue to Step 4.
+ - `## Related Knowledge` — wikilinks to other knowledge units, each with a brief note on the relationship. Omit it when there are none.
+ - `## Sources` — always the last section: one `- [[<note-stem>]]` per source note, never duplicated. The stem is the filename without path or extension (`/notes/2024-01-15 Weekly Review.md` → `[[2024-01-15 Weekly Review]]`).
- For every unit marked `update` in the manifest: read its existing file at `<knowledge-dir>/<unit-name>.md` now, before Step 4 begins. Do not proceed to Step 4 until all existing files are loaded.
+ **Frontmatter:**
+ ```yaml
---
-
- ## Step 4 — Compile
-
- For each unit in the manifest, check its `operation` and read the corresponding file:
-
- - **`create`** → read `references/create.md` and follow it completely.
- - **`update`** → read `references/update.md` and follow it completely.
-
-
- Complete one unit fully before moving to the next. After all units are done, confirm in prose: which were created, which updated, and what changed in each.
-
+ kind: knowledge
+ title: <Title>
+ entity_type: <freeform label>
+ tags: [tag1, tag2]
+ source_notes:
+ - /path/to/note.md
+ perspective: own # own | external | mixed
+ created_at: YYYY-MM-DDTHH:MM:SSZ
+ last_compiled_at: YYYY-MM-DDTHH:MM:SSZ
+ compile_count: 1
---
-
- ## Language
-
- Match the language of existing units in the knowledge directory. If no units exist, use the language of the source note. Dates are always `YYYY-MM-DD`. When the vault language is not English, translate all section names accordingly.
-
- ## Time attribution
-
- Knowledge units must anchor time to the **original publication date of the source material**, not the compilation date.
+ ```
- - If `source_date` is known: use it when writing any time-sensitive content in the unit (e.g. "as of YYYY-MM-DD", "at the time of publication").
- - If `source_date` is unknown: omit the time reference or mark it as "date unknown". Never substitute today's date.
+ **Tags.** Call `tag_list` first. Decide the tags that describe the unit, then swap each for an existing equivalent (same concept, other language or spelling: `独立开发` ↔ `indie-dev`). Keep a new tag only when no equivalent exists.