{"skill":{"slug":"knowledge-graph-skill","displayName":"Knowledge Graph","summary":"Embedded knowledge graph for persistent structured knowledge. ALWAYS use proactively — do NOT wait for user to ask. Auto-triggers on: (1) any mention of peop...","description":"---\nname: knowledge-graph\ndescription: \"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.\"\n---\n\n# Knowledge Graph Skill\n\nPersonal KG stored as JSON, queried via CLI scripts. Produces a compact KGML summary for session context.\nCore instructions are in AGENTS.md (auto-injected by install). This file covers setup, advanced usage, and reference only.\n\n## First-Time Setup\n\n```bash\nnode scripts/install.mjs [--workspace /path/to/workspace] [--platform openclaw|claude|gemini]\n```\nAuto-detects platform and patches the agent instructions file (`AGENTS.md`, `CLAUDE.md`, or `GEMINI.md`) with KG instructions + graph summary. Idempotent.\n\n## KGML Format Reference\n\n```\n#KGML v2 | <count>e <count>r | depth:<N> | <date>\n[category]\nLabel(Alias):type — attr1,attr2\n  ChildLabel(CA):type — attrs    ← indent = parent>child\n%rels\nA>verb>B C>verb>D                ← cross-branch relations (aliases)\n%vault key1,key2                 ← vault key names (no values)\n```\n\n## Advanced Query Commands\n\nBeyond the basics in AGENTS.md (`find`, `traverse`, `rels`):\n```bash\nnode scripts/query.mjs children <id>      # Direct children\nnode scripts/query.mjs type <type>         # All entities of a type\nnode scripts/query.mjs cat <category>      # All in category\nnode scripts/query.mjs orphans             # Unlinked entities\nnode scripts/query.mjs stats               # Graph statistics\nnode scripts/query.mjs recent [--days 7]   # Created/updated recently\nnode scripts/query.mjs timeline [--from YYYY-MM-DD] [--to YYYY-MM-DD]\nnode scripts/query.mjs changed             # Modified after creation\nnode scripts/query.mjs uncertain           # Confidence < 0.5\n```\n\n## Merge\n\n```bash\nnode scripts/merge.mjs --target <id> --source <id> --mode absorb|nest\n```\n\n## Vault (secrets)\n\n```bash\nnode scripts/vault.mjs set <key> <value> --note \"description\"\nnode scripts/vault.mjs get <key>          # Raw value (for piping)\nnode scripts/vault.mjs list               # Keys only\nnode scripts/vault.mjs del <key>\n```\n\n## Depth Heuristic — How Many Layers to Extract\n\nBefore adding a rich knowledge item (article, paper, report, system description), assess complexity first:\n\n```bash\n# Score text content and get recommended depth + checklist:\nnode scripts/depth-check.mjs \"paste text or summary here\"\necho \"article text\" | node scripts/depth-check.mjs\nnode scripts/depth-check.mjs --file /path/to/article.txt\nnode scripts/depth-check.mjs --json    # machine-readable\n\n# Score interpretation:\n# 0-1 → 1 layer (root only)\n# 2-3 → 2 layers (root + concepts)\n# 4-5 → 3 layers (root → domains → mechanisms)\n# 6-7 → 4+ layers (full extraction with orgs/events/policies + cross-relations)\n```\n\n**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.\n\n## Visualization\n\n```bash\nnode scripts/visualize.mjs                # → data/kg-viz.html\nnode scripts/visualize.mjs --output /tmp/graph.html\n```\nALWAYS use this script. Do NOT write custom HTML. Output is self-contained, offline, no CDN.\n\nParent edges render as **blue dashed arrows** (60% opacity). Regular edges are red solid arrows.\n\n## Configuration\n\nAll settings have sensible defaults. Override only what you need — config stores only your changes.\n\n```bash\nnode scripts/config.mjs                       # list all settings with current values\nnode scripts/config.mjs get <key>              # get a value (e.g. summary.tokenBudget)\nnode scripts/config.mjs set <key> <value>      # set a value\nnode scripts/config.mjs reset <key>            # reset single key to default\nnode scripts/config.mjs reset --all            # reset everything\nnode scripts/config.mjs --json                 # full config as JSON\n```\n\n### Available Settings\n\n| Section | Key | Default | Description |\n|---------|-----|---------|-------------|\n| **summary** | `tokenBudget` | 5000 | Max tokens for kg-summary.md |\n| | `maxChildDepth` | auto | Tree depth (null=auto: 3/<100, 2/100-400, 1/>400) |\n| | `maxAttrLen` | 40 | Max characters for attribute values |\n| | `maxPerRoot` | 4 | Max relations shown per root subtree |\n| | `compactThreshold` | 400 | Entity count for compact mode |\n| | `mediumThreshold` | 200 | Entity count for medium depth |\n| **validation** | `minEntities` | 30 | Min entities for extraction PASS |\n| | `minRelationRatio` | 0.5 | Relations per entity ratio |\n| | `minDepth` | 3 | Min hierarchy depth for PASS |\n| | `minEvents` | 3 | Min event nodes for PASS |\n| **depthCheck** | `entityCapForEstimate` | 50 | Cap NER count for target estimation |\n| | `minEntitiesMultiplier` | 1.0 | Named entities → min target multiplier |\n| | `extraEntities` | 30 | Added to min for max entity range |\n| **consolidation** | `autoNest` | true | Auto-nest single-relation orphans |\n| | `mergeSuggestions` | true | Suggest merges for similar labels |\n| | `pruneEmptyAttrs` | true | Remove empty/null attrs |\n| | `levenshteinThreshold` | 2 | Max edit distance for merge suggestions |\n| **visualization** | `repulsion` | 5000 | Physics repulsion force |\n| | `edgeRestLength` | 160 | Default edge rest length |\n| | `overlapPenalty` | 3 | Overlap repulsion multiplier |\n| | `simulationSteps` | 500 | Physics simulation iterations |\n| | `initialSpread` | 1.5 | Initial node spread multiplier |\n| | `zoomAnimationMs` | 400 | Zoom-to-node animation duration |\n\nConfig file: `data/kg-config.json` (per-agent, gitignored).\n\n## Cross-Agent Access (read-only)\n\n```javascript\nimport { createReader } from '<path-to-skill>/lib/reader.mjs';\nconst kg = createReader();\nkg.search(\"query\"); kg.traverse(\"id\", { depth: 2 }); kg.stats();\n```\nOr CLI: `node scripts/export.mjs --format json --target /path/to/output.json`\n\n## Memory Import\n\n```bash\nnode scripts/import-memory.mjs            # dry-run\nnode scripts/import-memory.mjs --apply    # add with confidence 0.5\n```\nThen: `node scripts/query.mjs uncertain` to review auto-imported entities.\n\n## Knowledge Entity Guide\n\nThe `knowledge` type covers both declarative and procedural knowledge. Use attrs and tags to differentiate:\n\n| Kind | Tags | Key attrs | Example |\n|------|------|-----------|---------|\n| Fact/finding | `#fact`, `#til` | `source`, `field`, `summary` | \"LLMs use ~4 chars per token\" |\n| Research/paper | `#paper`, `#research` | `source`, `field`, `summary`, `author` | AI alignment paper findings |\n| Idea | `#idea` | `summary`, `status` | \"Build a CLI for KG queries\" |\n| How-to/procedure | `#howto`, `#procedure` | `steps`, `context`, `summary` | \"How to deploy on Pi\" |\n| Mental model | `#mental-model`, `#framework` | `steps`, `context`, `summary` | \"Debug network: ping→DNS→firewall\" |\n| Workflow | `#workflow` | `steps`, `context`, `summary` | \"Code review: tests first, then impl\" |\n\n**Attrs for procedural knowledge:**\n- `steps`: ordered procedure as string (use `→` or numbered: `\"1. Check logs → 2. Reproduce → 3. Fix → 4. Test\"`)\n- `context`: when/where to apply this knowledge (e.g. `\"when network is down\"`, `\"during code review\"`)\n- `summary`: short description of what this knowledge is about\n\n## Consolidation\n\nRun `node scripts/consolidate.mjs` weekly or when entity count > 80. Then `summarize.mjs`.\n\n## Security\n\n- NEVER print vault values in chat or log to memory/ files\n- vault.enc.json and .vault-key must never be in context\n- Other agents: read-only via reader.mjs, NO write access\n","topics":["Debugging"],"tags":{"latest":"1.1.1"},"stats":{"comments":0,"downloads":1472,"installsAllTime":56,"installsCurrent":12,"stars":2,"versions":2},"createdAt":1772438991794,"updatedAt":1779077460027},"latestVersion":{"version":"1.1.1","createdAt":1772481508081,"changelog":"- Added quotes around the SKILL.md description field for improved formatting and compatibility.\n- No functional or behavioral changes; update is documentation-only.","license":null},"metadata":null,"owner":{"handle":"xnohat","userId":"s1774j57e0vwc117j5k22513mn87hjrm","displayName":"Hong Phuc Nguyen","image":"https://avatars.githubusercontent.com/u/4613808?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780089741107}}