Knowledge Graph Skill

Personal KG stored as JSON, queried via CLI scripts. Produces a compact KGML summary for session context. Core instructions are in AGENTS.md (auto-injected by install). This file covers setup, advanced usage, and reference only.

First-Time Setup

node scripts/install.mjs [--workspace /path/to/workspace] [--platform openclaw|claude|gemini]

Auto-detects platform and patches the agent instructions file (AGENTS.md, CLAUDE.md, or GEMINI.md) with KG instructions + graph summary. Idempotent.

KGML Format Reference

#KGML v2 | <count>e <count>r | depth:<N> | <date>
[category]
Label(Alias):type — attr1,attr2
  ChildLabel(CA):type — attrs    ← indent = parent>child
%rels
A>verb>B C>verb>D                ← cross-branch relations (aliases)
%vault key1,key2                 ← vault key names (no values)

Advanced Query Commands

Beyond the basics in AGENTS.md (find, traverse, rels):

node scripts/query.mjs children <id>      # Direct children
node scripts/query.mjs type <type>         # All entities of a type
node scripts/query.mjs cat <category>      # All in category
node scripts/query.mjs orphans             # Unlinked entities
node scripts/query.mjs stats               # Graph statistics
node scripts/query.mjs recent [--days 7]   # Created/updated recently
node scripts/query.mjs timeline [--from YYYY-MM-DD] [--to YYYY-MM-DD]
node scripts/query.mjs changed             # Modified after creation
node scripts/query.mjs uncertain           # Confidence < 0.5

Merge

node scripts/merge.mjs --target <id> --source <id> --mode absorb|nest

Vault (secrets)

node scripts/vault.mjs set <key> <value> --note "description"
node scripts/vault.mjs get <key>          # Raw value (for piping)
node scripts/vault.mjs list               # Keys only
node scripts/vault.mjs del <key>

Depth Heuristic — How Many Layers to Extract

Before adding a rich knowledge item (article, paper, report, system description), assess complexity first:

# Score text content and get recommended depth + checklist:
node scripts/depth-check.mjs "paste text or summary here"
echo "article text" | node scripts/depth-check.mjs
node scripts/depth-check.mjs --file /path/to/article.txt
node scripts/depth-check.mjs --json    # machine-readable

# Score interpretation:
# 0-1 → 1 layer (root only)
# 2-3 → 2 layers (root + concepts)
# 4-5 → 3 layers (root → domains → mechanisms)
# 6-7 → 4+ layers (full extraction with orgs/events/policies + cross-relations)

Key rule: Never stop at 2 layers for complex content. If score ≥ 4, extract all named orgs, events, policies, and cross-relations — not just the top-level themes.

Visualization

node scripts/visualize.mjs                # → data/kg-viz.html
node scripts/visualize.mjs --output /tmp/graph.html

ALWAYS use this script. Do NOT write custom HTML. Output is self-contained, offline, no CDN.

Parent edges render as blue dashed arrows (60% opacity). Regular edges are red solid arrows.

Configuration

All settings have sensible defaults. Override only what you need — config stores only your changes.

node scripts/config.mjs                       # list all settings with current values
node scripts/config.mjs get <key>              # get a value (e.g. summary.tokenBudget)
node scripts/config.mjs set <key> <value>      # set a value
node scripts/config.mjs reset <key>            # reset single key to default
node scripts/config.mjs reset --all            # reset everything
node scripts/config.mjs --json                 # full config as JSON

Available Settings

Section	Key	Default	Description
summary	`tokenBudget`	5000	Max tokens for kg-summary.md
	`maxChildDepth`	auto	Tree depth (null=auto: 3/<100, 2/100-400, 1/>400)
	`maxAttrLen`	40	Max characters for attribute values
	`maxPerRoot`	4	Max relations shown per root subtree
	`compactThreshold`	400	Entity count for compact mode
	`mediumThreshold`	200	Entity count for medium depth
validation	`minEntities`	30	Min entities for extraction PASS
	`minRelationRatio`	0.5	Relations per entity ratio
	`minDepth`	3	Min hierarchy depth for PASS
	`minEvents`	3	Min event nodes for PASS
depthCheck	`entityCapForEstimate`	50	Cap NER count for target estimation
	`minEntitiesMultiplier`	1.0	Named entities → min target multiplier
	`extraEntities`	30	Added to min for max entity range
consolidation	`autoNest`	true	Auto-nest single-relation orphans
	`mergeSuggestions`	true	Suggest merges for similar labels
	`pruneEmptyAttrs`	true	Remove empty/null attrs
	`levenshteinThreshold`	2	Max edit distance for merge suggestions
visualization	`repulsion`	5000	Physics repulsion force
	`edgeRestLength`	160	Default edge rest length
	`overlapPenalty`	3	Overlap repulsion multiplier
	`simulationSteps`	500	Physics simulation iterations
	`initialSpread`	1.5	Initial node spread multiplier
	`zoomAnimationMs`	400	Zoom-to-node animation duration

Config file: data/kg-config.json (per-agent, gitignored).

Cross-Agent Access (read-only)

import { createReader } from '<path-to-skill>/lib/reader.mjs';
const kg = createReader();
kg.search("query"); kg.traverse("id", { depth: 2 }); kg.stats();

Or CLI: node scripts/export.mjs --format json --target /path/to/output.json

Memory Import

node scripts/import-memory.mjs            # dry-run
node scripts/import-memory.mjs --apply    # add with confidence 0.5

Then: node scripts/query.mjs uncertain to review auto-imported entities.

Knowledge Entity Guide

The knowledge type covers both declarative and procedural knowledge. Use attrs and tags to differentiate:

Kind	Tags	Key attrs	Example
Fact/finding	`#fact`, `#til`	`source`, `field`, `summary`	"LLMs use ~4 chars per token"
Research/paper	`#paper`, `#research`	`source`, `field`, `summary`, `author`	AI alignment paper findings
Idea	`#idea`	`summary`, `status`	"Build a CLI for KG queries"
How-to/procedure	`#howto`, `#procedure`	`steps`, `context`, `summary`	"How to deploy on Pi"
Mental model	`#mental-model`, `#framework`	`steps`, `context`, `summary`	"Debug network: ping→DNS→firewall"
Workflow	`#workflow`	`steps`, `context`, `summary`	"Code review: tests first, then impl"

Attrs for procedural knowledge:

steps: ordered procedure as string (use → or numbered: "1. Check logs → 2. Reproduce → 3. Fix → 4. Test")
context: when/where to apply this knowledge (e.g. "when network is down", "during code review")
summary: short description of what this knowledge is about

Consolidation

Run node scripts/consolidate.mjs weekly or when entity count > 80. Then summarize.mjs.

Security

NEVER print vault values in chat or log to memory/ files
vault.enc.json and .vault-key must never be in context
Other agents: read-only via reader.mjs, NO write access

knowledge-graph