knowledge-graph

name

knowledge-graph

description

Embedded knowledge graph for persistent structured knowledge. ALWAYS use proactively — do NOT wait for user to ask. Auto-triggers on: (1) any mention of people, projects, devices, services, organizations, or infrastructure — search KG first, add if new, (2) decisions or architectural choices worth remembering, (3) credentials or API keys (store in vault), (4) relationships between entities (who owns what, what runs where, what depends on what), (5) recurring concepts, principles, or lessons learned, (6) preferences and opinions (likes, dislikes, reviews), (7) places and locations (where someone lives, travels, frequents), (8) life events and milestones (birthdays, trips, meetings), (9) habits and routines (daily patterns, recurring behaviors), (10) knowledge artifacts — research papers, articles, insights, ideas, interesting facts shared by the user, (11) know-how and procedures — how to do something, debugging approaches, workflows, mental models, problem-solving frameworks. Also use when recalling facts, answering questions about known entities, or needing structured context. Run install script on first use. NOT for: ephemeral daily notes (use memory/), transient conversation, or rapidly changing data.

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