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