> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rkat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WorkGraph

> Realm-scoped durable commitments, dependencies, readiness, claims, and evidence.

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.

## Mental Model

```text theme={null}
realm
  -> namespace
  -> work items
  -> dependency edges
  -> readiness
  -> claims
  -> evidence
  -> terminal state
```

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
* 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

| Need                                                           | Use                    |
| -------------------------------------------------------------- | ---------------------- |
| Shared durable work, dependencies, readiness, claims, evidence | WorkGraph              |
| One-off private scratch tracking                               | Builtin `task_*` tools |
| Time-based wakeups and recurrence                              | Schedule               |
| Recalled knowledge and compacted context                       | Memory                 |
| Live collaboration messages                                    | Comms                  |
| Executable multi-agent DAGs                                    | Mob Flow               |

## 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 default namespace is
`default`, but applications can use names such as `session/{id}`, `mob/{id}`,
or domain-specific namespaces. Namespaces are a scoping tool, not a promise
that every group is semantically meaningful.

## 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.

## See Also

* [WorkGraph guide](/guides/workgraph)
* [WorkGraph example](/examples/workgraph)
* [WorkGraph reference](/reference/workgraph-reference)
* [Scheduling](/concepts/scheduling)
* [Tools](/concepts/tools)