Knowledge Graph Notes

Automatically creates bidirectional links between related notes

Security Scan

The skill does what it says: it scans a notes directory, computes similarity scores, and can add bidirectional wikilinks — the requested files and behavior are internally consistent with that purpose.

Purpose & Capability

Name/description match the implementation: the code reads markdown/txt/org files, computes TF-IDF/Jaccard/structural signals, builds a graph, and produces/saves link suggestions or auto-links. There are no unrelated credentials or external services requested; reading and writing note files is appropriate for a note-linking tool.

Instruction Scope

The SKILL.md and code explicitly read a notes directory recursively and can modify notes by inserting auto-links (threshold ≥ 0.85). That behavior is consistent with the stated purpose but is an important side-effect: the skill will modify user files and writes a cache to the system temp directory. The SKILL.md does not strongly emphasize a safe dry-run or explicit confirmation before auto-applying changes.

Install Mechanism

Instruction-only skill with bundled Node.js scripts; there is no installer that downloads remote code. The included source files implement the functionality, so there is no external install/network retrieval risk in the manifest.

Credentials

No credentials or special environment variables are required. The code references standard environment variables (HOME, USERPROFILE, TEMP) to pick default paths — expected for a local file tool and proportionate to the stated purpose.

Persistence & Privilege

The skill is not force-enabled (always:false) and requires invocation. However, because the implementation can auto-modify files (and SKILL.md endorses 'Auto-link' for strong matches), allowlisting/autonomous invocation would let the agent modify your notes without further confirmation. This is not incoherent with the purpose, but it's a privilege the user should be aware of.

Assessment

This skill is coherent with its description: it scans a notes directory, computes similarity, and can insert wikilinks into your files. Before installing/running it: 1) Back up your notes or run the tool on a copy/test folder first. 2) Prefer a dry-run or export mode (inspect suggestions) instead of letting it auto-apply links; export.js and the SKILL.md indicate it will write auto-links for scores ≥ 0.85. 3) Confirm the notesPath argument (default is ~/.qclaw/workspace/) so it doesn't run against an unexpected directory. 4) Review the source (the bundled JS files) yourself if you want to ensure exact write behavior. 5) If you allow autonomous agent invocation, be aware the agent could trigger the skill and cause file edits — disable autonomous use or require explicit confirmation if you want tighter control.

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

{
  "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

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