What is the Knowledge Graph?
Every NSL program has a built-in knowledge graph (KG) that is automatically populated by cognitive statements. When you write belief weather = "sunny" confidence 0.8, a Belief node is created. When you write "rain" causes "flooding", two Causal nodes and a typed edge are created.
You never have to construct the graph manually -- it builds itself from your code.
15 Node Types
Belief Fact Goal Intent Constraint Observation Episode
Entity Causal Temporal Hypothesis Skill Capability Pursuit Invariant
17 Edge Types
Causes Because Triggers LeadsTo Requires Satisfies Contradicts
Supports Contains DependsOn Before After During Achieves
Pursues Monitors Produces
Auto-Population
Every cognitive statement creates nodes and edges:
| Statement | Creates |
|-----------|---------|
| belief x = val confidence 0.8 | Belief node |
| observe data as name | Observation node |
| "A" causes "B" | 2 Causal nodes + Causes edge |
| "A" triggers "B" | 2 Causal nodes + Triggers edge |
| goal name block | Goal node + Episode |
| monitor name safety target where cond | KGMonitor entry + Monitors edge |
| assuming cond block | Hypothesis node + Episode |
| after event block | Temporal node + After edge |
| crystallize "name" | Skill node |
| capability x = true | Capability entry |
| constraint fn(x) = x > 0 | Constraint node |
Querying
# Get all beliefs above a confidence threshold
let strong = kg.beliefs(0.7)
for each b in strong
print(f"{b.name}: {b.value} ({b.confidence})")
# Find a specific node
let node = kg.find("weather")
print(node.id, node.kind, node.confidence)
# Query by type
let goals = kg.query("goal")
let causal = kg.query("causal")
let temporal = kg.query("temporal")
# Causal chains
let causes_list = kg.causes(node.id) # what caused this?
let effects_list = kg.effects(node.id) # what does this cause?
# Shortest path between any two nodes
let path = kg.path(kg.find("rain").id, kg.find("flooding").id)
print(path) # list of node IDs
# Graph statistics
let stats = kg.stats()
print(f"Nodes: {stats.nodes}, Edges: {stats.edges}")
# Full dump
let dump = kg.dump() # {nodes, edges, episodes, capabilities}
Monitors: Reactive Safety
Monitors watch KG nodes and react to violations:
belief altitude = 150 confidence 0.9
# Safety -- throws immediately
monitor alt_check safety altitude where value > 100 "Altitude too low!"
# Hard -- throws on kg.check_monitors()
monitor temp_check hard temperature where confidence > 0.5 "Uncertain"
# Soft -- returns warnings
monitor quality soft data_quality where value > 0.7 "Quality low"
# Check
kg.check_monitors() # throws on hard/safety violations
let warnings = kg.check_soft() # list of warning strings
The checker expression has value, confidence, evidence, and name in scope from the watched node.
Building Causal Chains
"deforestation" causes "soil erosion"
"soil erosion" causes "flooding"
"flooding" causes "property damage"
"property damage" causes "insurance claims"
# Trace the full chain
let start = kg.find("deforestation")
let end_node = kg.find("insurance claims")
let chain = kg.path(start.id, end_node.id)
print(chain) # [id1, id2, id3, id4, id5]
# Get all downstream effects
let effects = kg.effects(start.id)
for each e in effects
print(f"Effect: {e.name}")
Consolidation
Merge low-confidence nodes and clean up the graph:
kg.consolidate(0.3) # merge nodes with confidence < 0.3
Capabilities (Permission Sandbox)
capability file_write = true "Needs to save data"
capability network = false "Offline mode"
if kg.capability("file_write")
file.write("output.txt", data)
if not kg.capability("network")
print("Running offline")