node scripts/install.mjs [--workspace /path/to/workspace] [--platform openclaw|claude|gemini]

#KGML v2 | e r | depth: | 
[category]
Label(Alias):type — attr1,attr2
  ChildLabel(CA):type — attrs    ← 缩进 = parent>child
%rels
A>verb>B C>verb>D                ← 跨分支关系（别名）
%vault key1,key2                 ← vault 键名（无值）

node scripts/query.mjs children       # 直接子节点
node scripts/query.mjs type          # 所有指定类型的实体
node scripts/query.mjs cat       # 所有指定类别的实体
node scripts/query.mjs orphans             # 未链接的实体
node scripts/query.mjs stats               # 图谱统计
node scripts/query.mjs recent [--days 7]   # 最近创建/更新的实体
node scripts/query.mjs timeline [--from YYYY-MM-DD] [--to YYYY-MM-DD]
node scripts/query.mjs changed             # 创建后修改过的实体
node scripts/query.mjs uncertain           # 置信度 < 0.5 的实体

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

node scripts/vault.mjs set   --note "description"
node scripts/vault.mjs get           # 原始值（用于管道）
node scripts/vault.mjs list               # 仅列出键
node scripts/vault.mjs del 

# 评分文本内容并获取推荐深度 + 清单：
node scripts/depth-check.mjs "粘贴文本或摘要"
echo "文章文本" | node scripts/depth-check.mjs
node scripts/depth-check.mjs --file /path/to/article.txt
node scripts/depth-check.mjs --json    # 机器可读格式
# 分数解读：
# 0-1 → 1 层（仅根节点）
# 2-3 → 2 层（根节点 + 概念）
# 4-5 → 3 层（根 → 领域 → 机制）
# 6-7 → 4+ 层（完整提取，包含组织/事件/策略 + 跨关系）

node scripts/visualize.mjs                # → data/kg-viz.html
node scripts/visualize.mjs --output /tmp/graph.html

node scripts/config.mjs                       # 列出所有设置及其当前值
node scripts/config.mjs get               # 获取值（例如 summary.tokenBudget）
node scripts/config.mjs set        # 设置值
node scripts/config.mjs reset             # 将单个键重置为默认值
node scripts/config.mjs reset --all            # 重置所有设置
node scripts/config.mjs --json                 # 完整配置以 JSON 格式输出

import { createReader } from '/lib/reader.mjs';
const kg = createReader();
kg.search("query"); kg.traverse("id", { depth: 2 }); kg.stats();

node scripts/import-memory.mjs            # 试运行
node scripts/import-memory.mjs --apply    # 以置信度 0.5 添加

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 | e r | depth: | 
[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       # Direct children
node scripts/query.mjs type          # All entities of a type
node scripts/query.mjs cat       # 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  --source  --mode absorb|nest

Vault (secrets)

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

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               # get a value (e.g. summary.tokenBudget)
node scripts/config.mjs set        # set a value
node scripts/config.mjs reset             # 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 '/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