Diagrams

Diagrams

diagram() documents a routine start to end as a graph, stored as type='diagram'. A node has a stable key, an objective label, a shape (start | step | decision | io | end) and an optional note carrying the reasoning; an edge carries the condition on a branch. Exactly one start is required and every node must be reachable from it; cycles are allowed.

Steps are addressable, which is what makes a diagram the index of its domain rather than prose: diagram_link() attaches a note/anti_pattern/reasoning to one step (visible from both ends), diagram_jump() continues a step into another flow (stored once, reported on both), diagram_node/diagram_edge patch one piece at a time.

Node positions are stored server-side, so every reader sees the same picture and an arrangement made in the dashboard persists; diagram_relayout() rebuilds them. get_diagram(uid, format=…) reads it back:

format	what it gives
svg-interactive	the canvas drawing in a pan/zoom shell — the one to show
svg	the same drawing as a plain file, to attach or link
mermaid	portable, but re-lays out and discards the stored positions
text	the prose projection kept as the memory's content
json	the full graph with positions, notes and links; the only round-trippable one

Both SVG formats write the markup to $MEMAI_HOME/renders/ and return the path plus a thin index of the steps. A render is a cache of a record that lives in the database, so it is swept per the retention setting in the dashboard.