ayushgoel Foam Notes
Overview
Maintains a Foam knowledge graph in the active workspace. Do not ask for a vault path — assume the user has the Foam repository open.
Default: update existing notes. Create new files only as a last resort.
Reference docs:
- Style rules and formatting:
references/foam-conventions.md - Note templates:
references/note-templates.md
Workflow
Step 1 — Find the right home
- Confirm scope — use the workspace root containing
.mdfiles and hub pages like_HOME.md. - Search for candidates — run
rgorgrepfor the topic in filenames,**Related:**lines, and##headings. No good search string? Glob all*.mdfiles. - Check for parent topics — if no exact match, ask: does this content belong inside an existing note as a
##section?
Decision (stop at first match):
- Exact or near-exact filename match → Update Note Workflow
- Sub-topic, variant, or application of an existing note → Update Note Workflow (add
##section) - Spans multiple notes as new connective insight → Update Note Workflow on each
- Genuinely standalone with no plausible parent → New Note Workflow
When in doubt between 2/3 and 4, choose update. New files add navigation cost; subsections are free.
New Note Workflow
- Name — Title Case with spaces (
Vector Databases.md). No date prefix, no underscores. - Draft using the template in
references/note-templates.md. - Link — pick 3–8 genuinely related notes for
**Related:**. - Back-link — open each related note and add a reciprocal
[[wikilink]]. - Check
_HOME.md— add a wikilink if the topic belongs to an existing section. - Write — see
references/foam-conventions.md. Use only information from the source.
Update Note Workflow
- Read the existing note fully before touching it.
- Diff — identify only information not already present (same concept restated = already present).
- Merge — add new subsections or bullets; do not rewrite or reorder existing content.
- Update
**Related:**if the source introduces new connections. - No timestamps — git history tracks changes.
Link Quality Rules
- Every note needs
**Related:**with at least one[[wikilink]]. - Glob
*.mdto confirm a file exists before writing any link. Never invent a target. - Prefer specific notes over broad hubs (
_HOME.md) unless the topic truly belongs there.
Example
User: "Add a note from this thread. Topic is log-structured merge trees."
- Search for
lsm,merge tree,log-structuredfrom workspace root. - No exact match, but
Storage Engines.mdcovers B-Trees and compaction — LSM trees are a sub-topic. - Update
Storage Engines.mdwith a new## Log-Structured Merge Treessection. - Only if the content is too large to fit cleanly does it graduate to its own file, linked back from
Storage Engines.md.
Common Mistakes
| Mistake | Correct behavior |
|---|---|
| Creating a new file for every new term | Check for a parent note first — add a ## section instead |
| Rewriting existing prose to "improve" it | Merge only; preserve existing wording |
| Inventing wikilink targets | Glob *.md to confirm the file exists first |
| Adding YAML frontmatter | The repo has no frontmatter — skip it |
| Adding "Updated:" timestamps | Git history serves this purpose |
| Duplicating content that exists in another note | Link to the other note instead |
Quick Reference
| Situation | Action |
|---|---|
| Topic file exists | Update — add only new info |
| Sub-topic / variant of existing note | Add ## section inside that note |
| Insight spanning multiple notes | Update each relevant note |
| No filename match, parent concept exists | Add ## section to parent |
| Genuinely standalone, no parent | New note workflow |
| Source contradicts existing note | Add note under relevant section; don't silently overwrite |