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 | \x3Ccount>e \x3Ccount>r | depth:\x3CN> | \x3Cdate>
[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 \x3Cid>      # Direct children
node scripts/query.mjs type \x3Ctype>         # All entities of a type
node scripts/query.mjs cat \x3Ccategory>      # 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 \x3C 0.5

Merge

node scripts/merge.mjs --target \x3Cid> --source \x3Cid> --mode absorb|nest

Vault (secrets)

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

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 \x3Ckey>              # get a value (e.g. summary.tokenBudget)
node scripts/config.mjs set \x3Ckey> \x3Cvalue>      # set a value
node scripts/config.mjs reset \x3Ckey>            # reset single key to default
node scripts/config.mjs reset --all            # reset everything
node scripts/config.mjs --json                 # full config as JSON

Available Settings

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

Cross-Agent Access (read-only)

import { createReader } from '\x3Cpath-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:

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