Skip to main content
WorkGraph is Meerkat’s durable commitment graph for agents. It answers:
  • what work exists?
  • what is blocked?
  • what is ready?
  • who claimed it?
  • what evidence supports completion?
  • what is terminally done, failed, or cancelled?
WorkGraph is realm-scoped and optional. It is not semantic memory, not schedule, and not the lightweight builtin task list. Enabling the work_graph capability is not enough by itself. Every agent build must also receive a host-issued WorkGraphNamespaceGrant for one exact realm and one immutable namespace. The service rejects cross-realm, cross-namespace, and all_namespaces requests through that grant.

​
Mental Model

A WorkItem is a durable commitment. Edges describe topology such as blocks, parent, related, supersedes, and derived_from. Readiness is derived by the WorkGraph subsystem from item state, time gates, claims, and topology.

​
What WorkGraph Owns

  • item lifecycle status
  • dependency legality and graph topology
  • readiness and claimability
  • claim ownership, leases, and revision checks
  • terminal state
  • evidence references
  • direct-child join policy
  • event history and current-state projections
Machines and services own these semantics. Tools and host surfaces act on or observe that state; they do not reinterpret it.

​
Boundaries

​
Mob Flow Execution Bindings

A WorkGraph item describes durable truth. A Mob Flow run is one bounded attempt to make that truth hold. Meerkat links them through a durable execution binding without merging their state machines. After authority admission, the binding is committed before Flow execution and records the exact mob, Flow, effective run-config digest, deterministic run id, activation parameters, idempotency key, and retry predecessor. WorkExecutionLifecycleMachine owns the cross-system handoff phases. Mob remains the only owner of run status and outputs. WorkGraph remains the only owner of evidence and completion policy. Launch realization has its own durable ordering. The Mob actor first persists the exact deterministic pending run, then advances the external-delivery ledger from begun to realizing, then commits the Mob lifecycle transition and starts execution. Consequently, a valid realizing record always has an independently observable run. A crash before pending-run persistence leaves a begun delivery whose absence can be adjudicated. A crash afterward recovers the same run instead of launching a replacement. A completed Flow therefore requests an idempotent evidence projection. It does not directly complete the item. The bridge then asks WorkGraph to close the item, and WorkGraph either admits closure under its policy or leaves the item open with the evidence attached. Execution evidence ids are reserved from general WorkGraph mutations. Recovery consumes an already committed execution evidence record before requiring the Mob run to remain present. Ambiguous launch is fail-closed. If the durable Mob delivery intent exists but the deterministic run is absent, reconciliation records launch_uncertain and does not blindly execute the Flow again. A realizing record without that run is a quarantine condition, not retry authority. Resolving it is an explicit exact-run recovery obligation. The public bridge has no caller-asserted break-glass transition; it remains fail-closed until the deterministic run is observed or a future sealed host authority proves a safe resolution.

​
Namespaces

Every item belongs to a realm and namespace. The standard persistent surfaces grant default. An embedding host may issue another namespace, but a session still receives exactly one grant and must use it consistently. Namespace renames are unsupported because the namespace is durable identity; archive the old namespace and mint a new one instead.

​
Parent And Child Joins

A parent edge points from child to parent. A parent is not ready while any direct child is active. Its failed_child_join_policy and cancelled_child_join_policy independently decide what terminal child failure or cancellation means:
  • require_success keeps the join unsatisfied.
  • propagate terminalizes the parent with the same failure class when a readiness/claim observation reconciles the join.
  • accept treats that child terminal as satisfying the join.
Both policies default to require_success. blocks edges are stricter: their source satisfies the edge only by reaching completed.

​
Durable Facts, Not Timers

WorkGraph commits typed facts such as item_ready, lease_expired, and namespace_terminal in the same durable mutation that first observes them. It never owns a timer or wake loop. Schedule or another trusted host may cause the observation; WorkGraph revalidates graph state and owns the resulting fact. An elapsed lease is therefore not silently released by wall-clock time alone.

​
Surfaces

Agents mutate general WorkGraph items through WorkGraph tools. Host APIs, REST, and CLI expose observability so humans and UIs can inspect items, ready work, snapshots, events, goal status, and attention bindings. CLI and trusted in-process hosts additionally expose narrow session-goal attention controls; public REST/RPC remain observational for those controls. The public Mob MCP surface exposes meerkat_workgraph_flow_launch, meerkat_workgraph_flow_reconcile, and meerkat_workgraph_flow_abandon_uncertain for managed Flow execution. Typed, redacted meerkat_workgraph_flow_binding_get and meerkat_workgraph_flow_binding_list tools expose linkage without activation parameters, idempotency material, correlation ids, or execution principals. Ordinary Flow status includes the same redacted reverse binding reference when the run belongs to a WorkGraph execution. The Mob host reconciles on startup and on Mob machine-state changes; explicit reconciliation is an observation/recovery trigger, not the liveness owner. A slow safety tick retries transient store or runtime failures that do not emit a watched state change. Remote members do not receive a replica of the WorkGraph store. The controlling host owns the binding, launches local or remotely placed Flow steps, and projects terminal evidence back into that same WorkGraph authority. Durable jobs compose through the same ownership rule. DetachedJobMachine owns execution and terminal result, while a terminal evidence projector adds a typed reference to the item and asks WorkGraph to close it under its existing completion policy. A scheduled job likewise leaves time with Schedule and execution with the jobs subsystem.

​
See Also