Knowledge Graph Notes

SKILL.md

---
description: Automatically creates bidirectional links between related notes
keywords: openclaw, skill, automation, ai-agent
name: skylv-note-linking
triggers: note linking
---

# SKILL.md — note-linking

> Auto-discover hidden connections between your notes. Bidirectional links, knowledge graphs, and semantic link suggestions — without plugins.

## What This Skill Does

Analyzes a directory of notes (markdown, txt, org, obsidian vault) and:

1. **Extracts** — reads all notes, splits by headings, extracts content blocks
2. **Understands** — detects entities (people, projects, topics, tools), infers relationships
3. **Links** — generates bidirectional link suggestions with confidence scores
4. **Graphs** — builds a knowledge graph showing how notes connect
5. **Queries** — traverse the graph: "show me all notes related to X", "who links to Y"

Unlike the incumbent `slipbot` (which does keyword matching), this skill uses **semantic understanding** — it knows that "LLM" relates to "language model" and "transformer architecture" even without exact keyword overlap.

---

## When to Trigger

Trigger when user says:
- "link my notes"
- "find connections between notes"
- "build a knowledge graph from my notes"
- "what relates to X in my notes"
- "show me all notes about Y"
- "I have notes scattered, can you organize them"
- "bidirectional links"
- "backlinks"
- "how does A connect to B"

---

## Input

| Field | Type | Description |
|-------|------|-------------|
| `notesPath` | string | Path to notes directory (default: `~/.qclaw/workspace/`) |
| `query` | string | Optional: specific question about note relationships |
| `depth` | number | Link traversal depth (default: 2) |
| `format` | string | `graph` / `list` / `markdown` (default: `markdown`) |

---

## Output

### Markdown Format (default)
```
## Knowledge Graph

### Notes Analyzed: 47
### Total Links Found: 134
### Orphan Notes: 3 (unconnected)

## Top Hubs (most linked)
1. **AI_Agent_Architecture.md** — 18 connections
2. **Memory_System_Design.md** — 14 connections
3. **GitHub_Strategy.md** — 11 connections

## Link Suggestions
| From | To | Confidence | Reason |
|------|----|-----------|--------|
| EvoMap.md | Memory_System_Design.md | 0.94 | Shared topic: self-evolution |
| GitHub_Strategy.md | clawhub_publish.md | 0.91 | Project: SKY-lv repo family |
| AI_Agent_Architecture.md | hermes-agent-integration.md | 0.87 | Tool integration |

## Backlinks
### EvoMap.md (3 backlinks)
← Memory_System_Design.md (self-repair loop concept)
← skill-market-analyzer.md (GEP protocol reference)
← agent-builder.md (evolution pattern)
```

### Graph Format
```json
{
  "nodes": [{"id": "note-name", "connections": 18, "topics": [...]}],
  "edges": [{"from": "A", "to": "B", "weight": 0.94, "reason": "..."}]
}
```

---

## Technical Approach

### Architecture
```
notesPath/
├── link_engine.js     ← Core: read → extract → analyze → graph
├── graph_query.js     ← Traverse graph, answer questions
└── export.js         ← Export as Obsidian markdown, JSON, CSV
```

### link_engine.js Core Logic

**Phase 1: Index**
- Recursively find all `.md`, `.txt`, `.org` files
- Parse frontmatter (YAML/toml headers)
- Split into content blocks (by heading or double newline)

**Phase 2: Entity Extraction**
- Named entities: people, organizations, tools (NER-lite regex)
- Topics: extract noun phrases, technical terms
- Keywords: TF-IDF top terms per note

**Phase 3: Relationship Detection**
```
Relationship Score = cosine_similarity(embedding_A, embedding_B)
```

Without external embedding APIs, use:
- **Keyword overlap** (Jaccard) weighted by TF-IDF
- **Co-occurrence** in same paragraph / section
- **Structural links**: same directory, similar filename, shared YAML tags
- **Explicit mentions**: [[wikilink]] or [note name] patterns

**Phase 4: Graph Construction**
```javascript
const graph = {
  nodes: Map<noteId, {file, topics, keywords, blocks}>,
  edges: Map<noteId, Map<noteId, {score, reasons, type}>>
}
```

**Phase 5: Query**
- Find shortest path between two notes
- List N-degree neighbors
- Find bridges (notes that connect otherwise separate clusters)

### Threshold Strategy
| Confidence | Condition | Action |
|-----------|-----------|--------|
| ≥ 0.85 | Strong semantic match | Auto-link (add `[[wikilink]]`) |
| 0.60–0.84 | Probable match | Suggest with reason |
| 0.40–0.59 | Weak match | Flag as "possible" |
| < 0.40 | Noise | Ignore |

---

## Implementation Notes

### Pure Node.js (no external APIs)
For embedding-free similarity, use:
1. **TF-IDF vectors** per note (term frequency × inverse document frequency)
2. **Jaccard similarity** on keyword sets
3. **Levenshtein distance** on headings to catch near-matches
4. **YAML tag intersection** for structured vaults

### Obsidian Compatibility
- Read existing `[[wikilink]]` syntax
- Write new links in Obsidian format
- Respect `![[embed]]` and `![[callout]]` patterns

### Performance
- Index vault once, cache in `~/.qclaw/note-linking-graph.json`
- Incremental update on file change (watch mode)
- Max file size: 1MB per note (skip binary/exec)

---

## Real Data (2026-04-11 Market Analysis)

| Metric | Value |
|--------|-------|
| Current incumbent | slipbot (score: 1.021) |
| Top target score | 3.5 |
| Gap | 3.43× improvement possible |
| Incumbent weakness | Keyword-only matching, no graph |

---

## Skills That Compose Well With

- `skylv-knowledge-graph` — if you want full graph visualization
- `skylv-file-versioning` — version your note graph over time
- `skylv-ai-prompt-optimizer` — optimize your note-taking prompts

## Usage

1. Install the skill
2. Configure as needed
3. Run with OpenClaw