Behavior Graphs
A behavior tree is only as good as the world model it reads from. A tree that ticks against stale state makes decisions on stale information. A tree that crashes loses its context. A tree that coordinates with other agents needs a shared medium.
ArcFlow solves all three: behavior trees as graph subgraphs, ticking against a live, persistent, spatial-temporal world model. The tree's decisions are grounded in real sensor state — position, confidence, observation class — and its execution history is queryable with the same GQL used for everything else.
How it works#
In ArcFlow, the behavior tree IS the world graph. Nodes are graph nodes. Execution order is edge traversal. The blackboard is node properties. The world state the tree reads from is the same graph it lives in.
What this gives you:
- Live world state — conditions read
_observation_class,_confidence, spatial position directly from the graph - Runtime modification — add, remove, or rewire behaviors with
MERGE/DELETEat runtime - Persistent — behavior state survives process restarts (WAL-backed)
- Temporal audit —
AS OF seq Nshows what the tree's blackboard looked like at any past tick - Multi-agent — multiple agents share one world model; their trees coordinate through shared graph state
Define a behavior tree#
-- Root: execute children in order, fail on first failure
CREATE (root:BT_Sequence {name: 'patrol', status: 'idle'})
-- Condition: checks the world model for a specific state
CREATE (check:BT_Condition {
name: 'obstacle_ahead',
query: 'MATCH (o:Obstacle) WHERE o._observation_class = "observed" AND o._confidence > 0.8 AND distance(o.position, ego.position) < 5.0 RETURN o',
status: 'idle'
})
-- Actions: perform work or modify the world model
CREATE (navigate:BT_Action {name: 'navigate_to_waypoint', status: 'idle', waypoint: 'wp_3'})
CREATE (avoid:BT_Action {name: 'avoid_obstacle', status: 'idle'})
CREATE (alert:BT_Action {name: 'send_alert', status: 'idle'})
-- Wire the tree
MATCH (root:BT_Sequence {name: 'patrol'})
MATCH (check:BT_Condition {name: 'obstacle_ahead'})
MERGE (root)-[:CHILD {order: 0}]->(check)
MATCH (root:BT_Sequence {name: 'patrol'})
MATCH (navigate:BT_Action {name: 'navigate_to_waypoint'})
MERGE (root)-[:CHILD {order: 1}]->(navigate)
-- Conditional branch on obstacle detection
MATCH (check:BT_Condition {name: 'obstacle_ahead'})
MATCH (avoid:BT_Action {name: 'avoid_obstacle'})
MERGE (check)-[:ON_SUCCESS]->(avoid)
MATCH (check:BT_Condition {name: 'obstacle_ahead'})
MATCH (alert:BT_Action {name: 'send_alert'})
MERGE (avoid)-[:ON_FAILURE]->(alert)Tick against live world state#
import { open } from '@ozinc/arcflow'
const db = open('./data/world-model')
// Tick reads live world model state — positions, confidence, observation class
function tick() {
db.query("CALL behavior.tick()")
const status = db.query("CALL behavior.status()")
for (const row of status.rows) {
console.log(`${row.get('name')}: ${row.get('status')}`)
}
}
// Run at 20Hz — behavior tree ticks against current world model state each time
setInterval(tick, 50)The world model is updated by sensors independently. When the spatial index changes (a new obstacle enters range), the next tick's condition check reflects it automatically.
Conditions that read world model state#
Behavior conditions can query the world model directly — confidence, observation class, spatial proximity:
-- Is there a high-confidence observed obstacle within 5 meters?
MATCH (ego:Robot {id: $robot_id})
CALL algo.nearestNodes(point({x: ego.x, y: ego.y}), 'Obstacle', 5)
YIELD node AS obs, distance
WHERE distance < 5.0
AND obs._observation_class = 'observed'
AND obs._confidence > 0.80
RETURN count(obs) AS blocking_count
-- Is the target zone clear?
MATCH (z:Zone {id: $target_zone})
MATCH (e:Entity)
WHERE e._observation_class IN ['observed', 'inferred']
AND distance(point({x: e.x, y: e.y}), point({x: z.x, y: z.y})) < 10.0
RETURN count(e) AS zone_occupancyThese queries fire inside the behavior tree tick — the tree sees the world at the exact moment of decision.
Dynamic modification at runtime#
// Enemy detected — inject an attack behavior without restarting
db.mutate("CREATE (attack:BT_Action {name: 'engage_target', status: 'idle', target_id: $id})", { id: contactId })
db.mutate(`
MATCH (root:BT_Sequence {name: 'patrol'})
MATCH (attack:BT_Action {name: 'engage_target'})
MERGE (root)-[:CHILD {order: 0}]->(attack)
`)
// Objective complete — remove the completed action
db.mutate("MATCH (a:BT_Action {name: 'engage_target'}) DETACH DELETE a")Temporal audit — what did the tree decide and why?#
Every tick is versioned in the world model:
-- What was the tree's blackboard state at tick 5000?
MATCH (n:BT_Sequence) AS OF seq 5000
RETURN n.name, n.status
-- What was the world model state when the tree failed?
MATCH (e:Entity) AS OF seq 4821
RETURN e.name, e.x, e.y, e._observation_class, e._confidencePost-incident analysis: replay the exact world state at the moment a decision was made. No log reconstruction — query the versioned graph directly.
Multi-agent behavior coordination#
Multiple agents share one world model. Their trees read the same ground truth:
-- Formation members sorted by position
MATCH (r:Robot)-[m:MEMBER_OF]->(f:Formation {name: 'Alpha'})
RETURN r.id, r.x, r.y, m.position
ORDER BY m.position
-- Assign the nearest idle robot to a task
MATCH (task:Task {status: 'pending'})
CALL algo.nearestNodes(point({x: task.x, y: task.y}), 'Robot', 5)
YIELD node AS robot, distance
WHERE robot.status = 'idle'
WITH robot, task ORDER BY distance LIMIT 1
SET robot.status = 'assigned', task.status = 'assigned'No message bus between agents. No shared-state synchronization layer. The world model is the shared state.
Node types#
| Type | Purpose | World Model integration |
|---|---|---|
BT_Sequence | Execute children left-to-right, fail on first failure | Reads spatial, confidence, observation class |
BT_Selector | Try children until one succeeds | Falls back on lower-confidence information |
BT_Condition | Check a predicate against the world model | Direct GQL query on graph state |
BT_Action | Perform work or mutate the world model | Writes back sensor readings, updates positions |
Edge types#
| Type | Purpose |
|---|---|
CHILD | Parent-to-child with order property for execution sequence |
ON_SUCCESS | Conditional branch on success |
ON_FAILURE | Conditional branch on failure |
Use cases#
- Autonomous robots — task planning, obstacle avoidance, sensor-driven recovery sequences grounded in live world model state
- UAV fleets — formation maintenance, mission assignment, live waypoint navigation
- Game AI — NPC decision-making that reads spatial proximity, inventory, and social state from a unified graph
- Simulation — population behavior modeling with persistent history and temporal replay
See Also#
- Building a World Model — the spatial-temporal foundation behavior trees read from
- Autonomous Systems — behavior trees in multi-robot coordination
- Live Queries — standing queries that trigger tree re-evaluation
- Skills — dynamic edge materialization from behavior outcomes