Skill: xnohat/knowledge-graph-skill (version 1.1.1)

--- 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 ```bash 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`): ```bash 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 ```bash node scripts/merge.mjs --target <id> --source <id> --mode absorb|nest ``` ## Vault (secrets) ```bash 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: ```bash # 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 ```bash 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. ```bash 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) ```javascript 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 ```bash 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


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)