--- name: graph version: "0.1.0" description: Interactive knowledge graph analysis. Routes natural language questions to graph scripts, interprets results in domain vocabulary, and suggests concrete actions. Triggers on "/graph", "/graph health", "/graph triangles", "find synthesis opportunities", "graph analysis". metadata: version: "1.0" generated_from: "arscontexta-v1.6" argument-hint: "[operation] [target] β€” operations: health, triangles, bridges, clusters, hubs, siblings, forward, backward, query" openclaw: emoji: "πŸ•ΈοΈ" --- ## Vault Path Resolution (mnemos) Before any file operations, resolve the vault root: 1. Read `.mnemos.yaml` from the workspace root (the project directory where you are running) 2. Extract `vault_path` β€” this is the root for ALL vault operations 3. All paths in this skill (notes/, ops/, inbox/, self/, memory/, templates/) are RELATIVE to vault_path 4. If `.mnemos.yaml` does not exist or vault_path is not set, fall back to the current working directory Example: if vault_path is `/data/vault`, then `ops/queue/queue.json` resolves to `/data/vault/ops/queue/queue.json`. ## Runtime Configuration (Step 0 β€” before any processing) Read these files to configure domain-specific behavior: 1. **`ops/derivation-manifest.md`** β€” vocabulary mapping, platform hints - Use `vocabulary.notes` for the notes folder name - Use `vocabulary.note` / `vocabulary.note_plural` for note type references - Use `vocabulary.topic_map` / `vocabulary.topic_map_plural` for MOC references - Use `vocabulary.cmd_reflect` for connection-finding command name - Use `vocabulary.cmd_reweave` for backward-pass command name 2. **`ops/config.yaml`** β€” for graph thresholds (MOC size limits, orphan thresholds) If no derivation file exists, use universal terms (notes, MOCs, etc.). --- ## EXECUTE NOW **Target: $ARGUMENTS** Parse the operation from arguments: - If arguments match a known operation: route to that operation - If arguments are a natural language question: map to the closest operation (see Interactive Mode) - If no arguments: enter interactive mode **START NOW.** Route to the appropriate operation. --- ## Philosophy **The graph IS the knowledge. This skill makes it visible.** Individual {vocabulary.note_plural} are valuable, but their connections create compound value. /graph reveals the structural properties of those connections β€” where the graph is dense, where it is sparse, where it is fragile, and where synthesis opportunities hide. Every operation produces two things: **findings** (what the analysis reveals) and **actions** (what to do about it). Never dump raw data. Always interpret results with {vocabulary.note} descriptions and domain context. Always suggest specific next steps. --- ## Operations ### /graph health Full graph health report: density, orphans, dangling links, coverage. **Step 1: Collect raw metrics** ```bash # Count total notes (excluding MOCs) NOTES_DIR="{vocabulary.notes}" TOTAL=$(ls -1 "$NOTES_DIR"/*.md 2>/dev/null | wc -l | tr -d ' ') MOC_COUNT=$(grep -rl '^type: moc' "$NOTES_DIR"/*.md 2>/dev/null | wc -l | tr -d ' ') NOTE_COUNT=$((TOTAL - MOC_COUNT)) # Count all wiki links LINK_COUNT=$(grep -ohP '\[\[[^\]]+\]\]' "$NOTES_DIR"/*.md 2>/dev/null | wc -l | tr -d ' ') # Calculate link density # Density = actual_links / possible_links # possible_links = N * (N - 1) for directed graph echo "Density: $LINK_COUNT / ($NOTE_COUNT * ($NOTE_COUNT - 1))" # Find orphan notes (zero incoming links) for f in "$NOTES_DIR"/*.md; do NAME=$(basename "$f" .md) INCOMING=$(grep -rl "\[\[$NAME\]\]" "$NOTES_DIR"/ 2>/dev/null | grep -v "$f" | wc -l | tr -d ' ') [[ "$INCOMING" -eq 0 ]] && echo "ORPHAN: $NAME" done # Find dangling links (links to non-existent files) grep -ohP '\[\[([^\]]+)\]\]' "$NOTES_DIR"/*.md 2>/dev/null | sort -u | while read -r link; do NAME=$(echo "$link" | sed 's/\[\[//;s/\]\]//') [[ ! -f "$NOTES_DIR/$NAME.md" ]] && echo "DANGLING: $NAME" done # MOC coverage: % of notes appearing in at least one MOC's Core Ideas COVERED=0 for f in "$NOTES_DIR"/*.md; do NAME=$(basename "$f" .md) # Skip MOCs themselves grep -q '^type: moc' "$f" 2>/dev/null && continue # Check if any MOC links to this note if grep -rl '^type: moc' "$NOTES_DIR"/*.md 2>/dev/null | xargs grep -l "\[\[$NAME\]\]" >/dev/null 2>&1; then COVERED=$((COVERED + 1)) fi done echo "Coverage: $COVERED / $NOTE_COUNT" ``` If graph helper scripts exist in `ops/scripts/graph/`, use them instead of inline analysis: - `ops/scripts/graph/link-density.sh` for density metrics - `ops/scripts/graph/orphan-notes.sh` for orphan detection - `ops/scripts/graph/dangling-links.sh` for dangling link detection **Step 2: Interpret and present** ``` --=={ graph health }==-- {vocabulary.note_plural}: [N] (plus [M] {vocabulary.topic_map_plural}) Connections: [N] (avg [X] per {vocabulary.note}) Graph density: [0.XX] {vocabulary.topic_map} coverage: [N]% of {vocabulary.note_plural} appear in at least one {vocabulary.topic_map} Orphans ([N]): - [[orphan name]] β€” [description from YAML] β†’ Suggestion: Run /{vocabulary.cmd_reflect} to find connections Dangling Links ([N]): - [[missing name]] β€” referenced from [[source note]] β†’ Suggestion: Create the {vocabulary.note} or remove the link {vocabulary.topic_map} Sizes: - [[moc name]]: [N] {vocabulary.note_plural} [OK | WARN: approaching split threshold | WARN: consider merging] Overall: [HEALTHY | NEEDS ATTENTION | FRAGMENTED] ``` **Density benchmarks:** | Density | Interpretation | |---------|---------------| | < 0.02 | Sparse β€” {vocabulary.note_plural} exist but connections are thin | | 0.02-0.06 | Healthy β€” growing network with meaningful connections | | 0.06-0.15 | Dense β€” well-connected, watch for over-linking | | > 0.15 | Very dense β€” verify connections are genuine, not noise | ### /graph triangles Find synthesis opportunities β€” open triadic closures where A links to B and A links to C, but B does not link to C. **Step 1: Build adjacency data** ```bash # For each note, extract outgoing wiki links for f in "$NOTES_DIR"/*.md; do NAME=$(basename "$f" .md) LINKS=$(grep -oP '\[\[([^\]]+)\]\]' "$f" 2>/dev/null | sed 's/\[\[//;s/\]\]//' | sort -u) echo "FROM:$NAME" echo "$LINKS" | while read -r target; do [[ -n "$target" ]] && echo " TO:$target" done done ``` If `ops/scripts/graph/find-triangles.sh` exists, use it directly. **Step 2: Find open triangles** For each note A with outgoing links to B and C: 1. Check if B links to C (in either direction) 2. Check if C links to B (in either direction) 3. If neither link exists: this is an open triangle (synthesis opportunity) **Step 3: Evaluate and rank** For each open triangle: 1. Read descriptions of BOTH unlinked {vocabulary.note_plural} 2. Assess: is there a genuine conceptual relationship that the common parent suggests? 3. Rank by potential value: how surprising and useful would the connection be? **Step 4: Present top findings** ``` --=={ graph triangles }==-- Found [N] synthesis opportunities β€” pairs of {vocabulary.note_plural} that share a common reference but do not reference each other: 1. [[note B]] and [[note C]] Common parent: [[note A]] B: "[description]" C: "[description]" β†’ These may benefit from a connection because [specific reasoning about WHY B and C might relate through A's lens] β†’ Action: Run /{vocabulary.cmd_reflect} on [[note B]] to evaluate 2. [[note D]] and [[note E]] Common parent: [[note F]] ... [Show top 10. If more exist: "[N] more triangles found. Show all? (yes/no)"] ``` **Filter out trivial triangles:** Skip pairs where: - Both are in the same {vocabulary.topic_map} (they may already be related through the MOC without direct links) - One is a {vocabulary.topic_map} itself (MOCs link to everything, triangles with MOCs are noise) - The descriptions suggest no conceptual overlap ### /graph bridges Identify structurally critical {vocabulary.note_plural} whose removal would disconnect graph regions. **Step 1: Build adjacency list** Build a bidirectional adjacency list from all wiki links in {vocabulary.notes}/. If `ops/scripts/graph/find-bridges.sh` exists, use it directly. **Step 2: Find bridge nodes** A bridge note is one where: - Removing it (and its links) would split a connected component into two or more components - It is the SOLE connection between clusters of {vocabulary.note_plural} Implementation: For each note, temporarily remove it and check if the remaining graph has more connected components. **Step 3: Present findings** ``` --=={ graph bridges }==-- Found [N] bridge {vocabulary.note_plural} β€” structurally critical nodes whose removal would disconnect graph regions: 1. [[bridge note]] β€” connects [N] {vocabulary.note_plural} on one side to [M] on the other Description: "[description]" Cluster A: [[note1]], [[note2]], ... Cluster B: [[note3]], [[note4]], ... β†’ Risk: If this {vocabulary.note} becomes stale, [N+M] {vocabulary.note_plural} lose their connection path β†’ Action: Consider adding parallel connections between the clusters [If no bridges: "No bridge notes found. The graph has redundant paths between all connected regions. This is healthy."] ``` ### /graph clusters Discover connected components and topic boundaries. **Step 1: Build adjacency list** Build a bidirectional adjacency list from all wiki links. If `ops/scripts/graph/find-clusters.sh` exists, use it directly. **Step 2: Find connected components** Use BFS/DFS to find all connected components: 1. Start with any unvisited note 2. Traverse all reachable notes via wiki links (bidirectional) 3. Mark as one component 4. Repeat until all notes visited **Step 3: Analyze clusters** For each cluster: - Size (number of {vocabulary.note_plural}) - Key {vocabulary.note_plural} (highest link count within cluster) - Topic coverage (which {vocabulary.topic_map_plural} are represented) - Isolation level (how many links cross cluster boundaries) **Step 4: Present findings** ``` --=={ graph clusters }==-- Found [N] connected components: Cluster 1: [size] {vocabulary.note_plural} Key nodes: [[note1]] (8 links), [[note2]] (6 links) Topics: [[topic A]], [[topic B]] Cross-cluster links: [N] β†’ This cluster is [well-connected | isolated | a hub] Cluster 2: [size] {vocabulary.note_plural} ... Isolated {vocabulary.note_plural} ([N]): - [[isolated note]] β€” [description] β†’ Action: Run /{vocabulary.cmd_reflect} to find connections [If 1 cluster: "All {vocabulary.note_plural} are in one connected component. The graph is fully connected. This is healthy."] ``` ### /graph hubs Rank {vocabulary.note_plural} by influence β€” most-linked-to (authorities) and most-linking-from (hubs). **Step 1: Count links** ```bash # Authority score: incoming links per note for f in "$NOTES_DIR"/*.md; do NAME=$(basename "$f" .md) INCOMING=$(grep -rl "\[\[$NAME\]\]" "$NOTES_DIR"/ 2>/dev/null | grep -v "$f" | wc -l | tr -d ' ') echo "AUTH:$INCOMING:$NAME" done | sort -t: -k2 -rn | head -10 # Hub score: outgoing links per note for f in "$NOTES_DIR"/*.md; do NAME=$(basename "$f" .md) OUTGOING=$(grep -oP '\[\[[^\]]+\]\]' "$f" 2>/dev/null | wc -l | tr -d ' ') echo "HUB:$OUTGOING:$NAME" done | sort -t: -k2 -rn | head -10 ``` If `ops/scripts/graph/influence-flow.sh` exists, use it directly. **Step 2: Identify synthesizers** Synthesizer {vocabulary.note_plural} score high on BOTH metrics β€” they absorb many inputs (high authority) and produce many outputs (high hub). These are the most structurally important {vocabulary.note_plural} in the graph. **Step 3: Present findings** ``` --=={ graph hubs }==-- Top Authorities (most-linked-to): 1. [[note]] β€” [N] incoming links β€” "[description]" 2. [[note]] β€” [N] incoming links β€” "[description]" ... Top Hubs (most-linking-from): 1. [[note]] β€” [N] outgoing links β€” "[description]" 2. [[note]] β€” [N] outgoing links β€” "[description]" ... Synthesizers (high on both β€” structurally important): 1. [[note]] β€” [N] in / [M] out β€” "[description]" ... [If no clear synthesizers: "No notes score high on both metrics. This suggests the graph has separate input and output layers."] ``` ### /graph siblings [[topic]] Find unconnected {vocabulary.note_plural} within a topic β€” {vocabulary.note_plural} sharing the same {vocabulary.topic_map} but not linking to each other. **Step 1: Read the specified {vocabulary.topic_map}** Find and read the {vocabulary.topic_map} matching the argument. Extract all {vocabulary.note_plural} linked in Core Ideas. **Step 2: Check pairwise connections** For each pair of {vocabulary.note_plural} in the {vocabulary.topic_map}: 1. Does A link to B? (grep for `[[B]]` in A's file) 2. Does B link to A? (grep for `[[A]]` in B's file) 3. If neither: this is an unconnected sibling pair If `ops/scripts/graph/topic-siblings.sh` exists, use it with the topic argument. **Step 3: Evaluate pairs** For each unconnected pair: - Read both descriptions - Assess whether a connection SHOULD exist - Rate as: likely connection, possible connection, appropriately separate **Step 4: Present findings** ``` --=={ graph siblings: [[topic]] }==-- {vocabulary.topic_map} [[topic]] has [N] {vocabulary.note_plural}. Found [M] unconnected sibling pairs: Likely connections: 1. [[note A]] and [[note B]] A: "[description]" B: "[description]" β†’ [Why these likely relate] Possible connections: 2. [[note C]] and [[note D]] ... Appropriately separate: [N] pairs β€” no connection needed β†’ Action: Run /{vocabulary.cmd_reflect} on the "likely" pairs ``` ### /graph forward [[note]] [depth] N-hop forward traversal from a {vocabulary.note}. Default depth: 2. **Step 1: Start from the specified {vocabulary.note}** Read the {vocabulary.note} and extract all outgoing wiki links (hop 1). If `ops/scripts/graph/n-hop-forward.sh` exists, use it with the note and depth arguments. **Step 2: Traverse** For each linked {vocabulary.note}: 1. Read it and extract its outgoing wiki links (hop 2) 2. Continue to specified depth 3. Track visited notes to avoid cycles **Step 3: Present as annotated tree** ``` --=={ forward traversal: [[note]] (depth [N]) }==-- [[root note]] β€” "[description]" β”œβ”€β”€ [[link 1]] β€” "[description]" β”‚ β”œβ”€β”€ [[link 1a]] β€” "[description]" β”‚ └── [[link 1b]] β€” "[description]" β”œβ”€β”€ [[link 2]] β€” "[description]" β”‚ └── [[link 2a]] β€” "[description]" └── [[link 3]] β€” "[description]" Reached [N] {vocabulary.note_plural} in [depth] hops. Dead ends (no outgoing links): [[note X]], [[note Y]] Cycles detected: [[note]] β†’ ... β†’ [[note]] (skipped) ``` ### /graph backward [[note]] [depth] N-hop backward traversal to a {vocabulary.note}. Default depth: 2. **Step 1: Start from the specified {vocabulary.note}** Find all notes that link TO this {vocabulary.note} (hop 1). ```bash NAME="[note name]" grep -rl "\[\[$NAME\]\]" "$NOTES_DIR"/*.md 2>/dev/null ``` If `ops/scripts/graph/recursive-backlinks.sh` exists, use it with the note and depth arguments. **Step 2: Traverse backward** For each linking {vocabulary.note}: 1. Find what links to IT (hop 2) 2. Continue to specified depth 3. Track visited notes to avoid cycles **Step 3: Present as annotated tree** ``` --=={ backward traversal: [[note]] (depth [N]) }==-- [[root note]] β€” "[description]" β”œβ”€β”€ [[referrer 1]] β€” "[description]" β”‚ β”œβ”€β”€ [[referrer 1a]] β€” "[description]" β”‚ └── [[referrer 1b]] β€” "[description]" β”œβ”€β”€ [[referrer 2]] β€” "[description]" β”‚ └── [[referrer 2a]] β€” "[description]" └── [[referrer 3]] β€” "[description]" [N] {vocabulary.note_plural} lead to [[root note]] within [depth] hops. Entry points (no incoming links): [[note X]], [[note Y]] ``` ### /graph query [field] [value] Schema-level YAML query across {vocabulary.note_plural}. **Step 1: Parse field and value** Supported query patterns: | Query | Ripgrep Pattern | Purpose | |-------|----------------|---------| | `topics [[X]]` | `rg '^topics:.*\[\[X\]\]'` | Find notes in a topic | | `type tension` | `rg '^type: tension'` | Find notes by type | | `methodology X` | `rg '^methodology:.*X'` | Find notes by tradition | | `status open` | `rg '^status: open'` | Find notes by status | | `created 2026-02` | `rg '^created: 2026-02'` | Find notes by date range | | `source [[X]]` | `rg '^source:.*\[\[X\]\]'` | Find notes from a source | **Step 2: Execute query** ```bash rg "^{field}:.*{value}" "$NOTES_DIR"/*.md -l 2>/dev/null ``` For each matching file, extract the description for context. **Step 3: Present results** ``` --=={ graph query: {field} = {value} }==-- Found [N] {vocabulary.note_plural}: 1. [[note name]] β€” "[description]" 2. [[note name]] β€” "[description]" ... Distribution: [If querying topics: how many per sub-topic] [If querying type: breakdown by status] [If querying methodology: breakdown by tradition] ``` --- ## Interactive Mode If no arguments provided: 1. Ask: "What would you like to know about your knowledge graph?" 2. Map natural language to operation: | User Says | Maps To | Why | |-----------|---------|-----| | "Where should I look for connections?" | triangles | Finding synthesis opportunities | | "What are my most important notes?" | hubs | Authority/hub ranking | | "Are there isolated areas?" | clusters | Connected component detection | | "How healthy is my graph?" | health | Full health report | | "What bridges my topics?" | bridges | Bridge note identification | | "What connects to [[X]]?" | backward [[X]] | Backward traversal | | "Where does [[X]] lead?" | forward [[X]] | Forward traversal | | "Show me notes about [topic]" | query topics [[topic]] | Schema query | | "What needs connecting in [topic]?" | siblings [[topic]] | Unconnected sibling pairs | 3. Run the mapped operation 4. After presenting results, offer follow-up: "Want to explore any of these further?" --- ## Output Rules - **Never dump raw data.** Always interpret results with {vocabulary.note} descriptions and context. - **Always suggest actions.** "Run /{vocabulary.cmd_reflect} on these pairs" or "Consider adding a bridge {vocabulary.note} about X." - **Use domain vocabulary** for all labels and descriptions β€” {vocabulary.note}, {vocabulary.topic_map}, etc. - **For large result sets,** summarize top findings (max 10) and offer to show more: "[N] more results. Show all? (yes/no)" - **Include density benchmarks** for context β€” "your density of 0.04 is in the healthy range." - **Distinguish structural from semantic.** Graph analysis reveals structural properties. Semantic judgment about WHETHER connections should exist requires /{vocabulary.cmd_reflect}. --- ## Edge Cases ### Small Vault (<10 notes) Report metrics but contextualize: "With [N] {vocabulary.note_plural}, graph analysis provides limited insight. Graph operations become more valuable as the knowledge graph grows. Current metrics are baseline measurements." All operations still run β€” they just produce less data. ### No Graph Scripts Available If `ops/scripts/graph/` does not exist or individual scripts are missing, implement the analysis inline using grep, file reads, and bash loops as shown in each operation's steps. The inline implementations are complete β€” scripts are optimization, not requirements. ### No ops/derivation-manifest.md Use universal vocabulary (notes, MOCs, etc.). All operations work identically. ### Empty Notes Directory Report: "No {vocabulary.note_plural} found in {vocabulary.notes}/. Start by capturing content to build your knowledge graph." ### Note Not Found (for forward/backward/siblings) If the specified {vocabulary.note} or {vocabulary.topic_map} does not exist: 1. Search for partial matches: `ls "$NOTES_DIR"/*{query}*.md 2>/dev/null` 2. If matches found: "Did you mean: [[match1]], [[match2]]?" 3. If no matches: "{vocabulary.note} '[[name]]' not found. Check the name and try again."