pkm-write

# PKM Write — Vault Writing with Knowledge Graph Integration

Follow these steps when creating new notes. When running as a subagent, the delegation prompt provides the note topic and project context.

## Step 1: Duplicate Check

Before creating, search for existing notes on the same topic:

```
vault_semantic_search({ query: "<topic/title of intended note>", limit: 5 })
```

If `vault_semantic_search` is unavailable (no `VAULT_PKM_OPENAI_KEY`), use `vault_search` with the note's title and key terms, and `vault_query` with matching tags to check for duplicates.

**Route based on results.** Note on score interpretation: `vault_semantic_search` uses `text-embedding-3-large` (3072-dim) cosine similarity, which compresses hard. Even a verbatim title/heading of an existing note typically scores around 0.55–0.65 against that note; scores above 0.7 are essentially never observed. Read the scores with that scale in mind.

- **Likely duplicate (top hit ≥ 0.5)**: Read the top hit with `vault_read` and confirm it's actually about the same topic before routing — a 0.5 score can be a real duplicate or a same-domain neighbor. If it IS the same topic: **update the existing note** instead of creating a new one — `vault_append` to add new content or `vault_edit` to refine existing content; `vault_update_frontmatter` if metadata changed. Skip to Step 4 (Discover Connections) after updating. If it's a same-domain neighbor (related but distinct topic), treat as a partial match.
- **Partial matches (top hit < 0.5, or top hit ≥ 0.5 but verified as a neighbor)**: Mention as potentially related, proceed with creation at Step 2. Link to them in Step 6.
- **No matches at all**: Proceed with creation at Step 2.

## Step 2: Create the Note

Use `vault_write` with the appropriate template. Select the template and path based on content type:

| Content Type | Template | Default Path |
|---|---|---|
| Architecture decision | `adr` | `<project>/development/decisions/ADR-NNN-{title}.md` |
| Research finding | `research-note` | `<project>/research/{title}.md` |
| Bug investigation | `troubleshooting-log` | `<project>/development/debug/{title}.md` |
| Reusable knowledge | `permanent-note` | `03-Resources/Development/{title}.md` |
| Task | `task` | `<project>/tasks/{title}.md` |
| Meeting record | `meeting-notes` | `<project>/planning/{title}.md` |
| Literature/article notes | `literature-note` | `03-Resources/{title}.md` |

Where `<project>` is the vault project path (e.g., `01-Projects/MyApp`). Determine from the delegation prompt, CLAUDE.md `# PKM:` annotation, or SessionStart hook context.

**Notes in `03-Resources/`** should be written as project-agnostic knowledge — useful regardless of where the insight originated. Use frontmatter tags or `## Related` links to trace the origin project, but write the content for a general audience.

If CLAUDE.md specifies a different location for a content type, use that instead.

```
vault_write({
  template: "<template>",
  path: "<path-from-table>",
  frontmatter: { tags: [...], ... }
})
```

Ensure:
- At least one meaningful tag
- `{title}` uses kebab-case (e.g., `cache-eviction-strategies`)
- For ADRs, use `vault_list` on the decisions directory to determine the next NNN number

## Step 3: Populate Content

`vault_write` creates a skeleton from the template — headings with HTML comment placeholders and empty bullets. You must fill in the actual content.

1. **Read the note** with `vault_read` to see the exact template output
2. **Replace placeholders** with `vault_edit`, using the exact text from the read output as `old_string`

Work section by section. Each `vault_edit` call must match text **exactly as it appears in the file** — do NOT guess what the template produced.

For templates with many sections, you can batch multiple sections into fewer edits by using a larger `old_string` that spans consecutive sections.

**Don't forget the link sections.** Templates include link sections like `## Related`, `## Links`, and `## References` with their own placeholder block — an HTML comment plus an empty bullet. The exact comment text varies per template (e.g., `<!-- Format: - [[note-name]] — relationship explanation -->` in most templates, `<!-- External references: docs, articles, repos -->` in research-note's `## Links`). Read the file first to get the exact placeholder text, then `vault_edit` to remove it. `vault_add_links` in Step 6 *appends* new links below whatever already exists in the section — it does not replace the placeholder, so leftover stubs end up sitting above the real links.

## Step 4: Discover Connections

Run `vault_suggest_links` on the new note to find related content:

```
vault_suggest_links({ path: "<path-to-new-note>", limit: 8 })
```

Select the top **3–5** most relevant suggestions.

If `vault_suggest_links` is unavailable (no `OPENAI_API_KEY`), use `vault_search` with key terms from the note's title/topic and `vault_query` with matching tags to manually identify good link targets.

If **no suggestions are returned** (new vault or isolated topic), skip Steps 5–7 — the note's `## Related` section will be filled as the graph grows.

**Well-linked-existing-note carve-out (UPDATE path only).** If you arrived here via the Step 1 UPDATE branch and the existing note's `## Related` already covers the connections you would otherwise add — i.e., the top suggestions from `vault_suggest_links` are already linked, or are clearly weaker than what's already there — skip Steps 5–7. Forcing additional links to a note that's already well-curated degrades link quality. This carve-out applies only to UPDATE; new notes always work through Steps 5–7.

## Step 5: Draft Annotations

For each selected link, write a one-line annotation explaining the relationship.

**Good annotations** use specific relationship language:
- "builds on", "supersedes", "implements", "contradicts", "provides context for", "extends", "is an instance of"

**Bad**: `- [[note]] — related to this topic`
**Good**: `- [[architecture-patterns]] — foundational patterns this decision builds on`

Use the note's content, shared tags, and conversation context to produce meaningful explanations.

## Step 6: Insert Links

Add annotated links to the note using `vault_add_links`:

```
vault_add_links({
  path: "<path-to-new-note>",
  links: [
    { target: "<vault-relative-path>", annotation: "relationship explanation" },
    { target: "<vault-relative-path>", annotation: "relationship explanation" }
  ]
})
```

The tool handles deduplication (skips already-linked targets), creates `## Related` if missing, and validates targets exist. Format annotations as specific relationship language (see Step 5).

If the note uses a non-standard section (e.g., `## References`), pass `section: "## References"`.

If the template does not include a `## Related` section, `vault_add_links` will create it automatically (default `create_section: true`). Templates with `## Related` built in: adr, permanent-note, research-note, troubleshooting-log, literature-note, moc, meeting-notes.

Note: MOC notes created before this version may use `## Related Topics` instead of `## Related`. If `vault_add_links` fails with "Section not found", try `section: "## Related Topics"`.

## Step 7: Bidirectional Linking

For **significant note types** (ADR, permanent-note, research-note, troubleshooting-log, literature-note, moc, meeting-notes):
- Check if the top 1–2 target notes would benefit from a backlink to this new note
- If yes, add a backlink to their `## Related` section using `vault_add_links`

**Skip** for ephemeral types (fleeting-note, daily-note) — Obsidian's native backlinks panel is sufficient.

## Step 8: Index Update

- If the note is an **ADR**: add a wikilink to the project's `_index.md`
- If the note is **project-scoped**: ensure the project `_index.md` references it where appropriate

---

## Modifying Existing Notes

Guidelines for edits, appends, and frontmatter updates. These don't require the full creation workflow above.

### vault_edit — Surgical String Replacement

- Check if edits affect link targets: renaming a heading breaks `[[note#heading]]` wikilinks pointing to it
- After significant content changes, consider running `vault_suggest_links` to discover new connections worth adding

### vault_append — Adding Content

- **Devlog entries**: Use `vault_append({ heading: "## Sessions", position: "after_heading" })` for reverse-chronological ordering
- **Section additions**: Specify the `heading` param to insert in the right location rather than appending at EOF

### vault_update_frontmatter — Atomic Field Updates

- Prefer `vault_update_frontmatter` over `vault_edit` for YAML fields — it parses and re-serializes safely
- Protected fields (`type`, `created`, `tags`) can be updated but not removed
- Task status/priority have enum validation: `status` must be pending/active/done/cancelled, `priority` must be low/normal/high/urgent