Momentum: Keep This Moving
A deep dive into scheduled workflow loops — scheduler, executor, condition memory, capability resolution, and failure modes.
The problem: workflows that die when the chat ends
You describe what you want. The agent runs it once. You get a useful result. Then Monday arrives and you type the same prompt again.
That is not a platform gap — it is a lifecycle gap. One-shot execution treats every request as ephemeral. Momentum treats successful work as something worth keeping.
"Keep this moving" is not a button on a chat UI. It is a first-class object with triggers, policies, provenance, and human gates.
Canon reference: kb/22_humanos_orchestration_core.md · PRD: plans/companion_intent_momentum_prd.md.
Mechanism walkthrough
1. Object creation
POST /v1/momentum persists a momentum_objects row: goal, triggers, capability families, delivery, and policies. Status starts at draft until capabilities and permissions are satisfied.
The SDK fluent builder is Principle #14 in action — build(goal).every('8am').using(['slack']).create() with full override paths on CreateMomentumOptions.
2. Activation and scheduling
POST /v1/momentum/:id/activate transitions draft → active and calls momentum-scheduler.ts, which registers an Inngest cron (or condition poll) from the object's trigger. Pause/resume unregisters and re-registers without losing configuration.
3. Run execution
momentum-executor.ts on each trigger:
- Reads the Momentum config
- Compiles a
WorkflowConfigContractvia existing workflow primitives - Routes through the HumanOS pipeline (delegation + capability checks)
- Writes
momentum_runswith status, duration, cost, output fingerprint - Emits gate events (
workflow_run,setup_completed)
Manual runs use POST /v1/momentum/:id/run with trigger_reason: manual.
4. Condition monitoring and previous-run memory
Condition triggers (kind: condition) register evaluation windows. After each successful run, the executor stores output_fingerprint. GET /v1/momentum/:id/runs/latest compares fingerprints to detect meaningful change — notification policy uses this to avoid noisy pushes.
5. Capability resolution
required_capabilities and installed_capabilities track the capability graph bindings. POST /v1/momentum/:id/capabilities/discover ranks marketplace connectors by fit (stub until Plans 20+25 deliver full resolver). Connectors declare momentum_capabilities in their manifest so resolution is deterministic.
6. Delivery and human gates
approval_policy and routing_policy enforce Human-in-the-Loop: low confidence routes to human_review, high-cost runs can require approval. Delivery respects notification_policy.urgency_threshold — meaningful by default, not every run.
Failure modes
| Symptom | Likely cause | Recovery |
|---|---|---|
needs_capability |
No connector bound for a required family | Install connector; capabilities/install or Companion setup canvas |
needs_permission |
Delegation missing connector scopes | Re-mint delegation with required scopes |
Run failed |
Upstream connector error or workflow compile issue | human momentum logs <id>; fix connector auth |
No next_run_at while active |
Invalid cron or scheduler registration failed | human momentum doctor <id>; re-activate |
| Duplicate notifications | Notification policy set to all on stable outputs |
Set urgency_threshold: meaningful |
| 409 on pause/resume | Idempotent state transition | Check current status with get |
Tie-back to Canon principles
| Principle | How Momentum embodies it |
|---|---|
| #1 Human Sovereignty | Objects are org-scoped; owner DID recorded; provenance receipts per run |
| #5 Human-in-the-Loop | Approval policies, awaiting_human run status, pause without data loss |
| #14 Magic by Default | Fluent SDK builder + templates; cron from natural language; zero schema required for first run |
What's next
- Flow A hook: After Intent workflow success, Companion offers "Keep this moving →" (idempotent per
canonical_intent_id). - Capability discovery: Full
LocalCapabilityResolverwhen Plans 20+25 land — stub routes exposed asx-mcp-tool: expose: falseuntil then. - Companion canvases:
momentum_hubandmomentum_run_resultrender in Companion Chrome (Plan 54 dependency). - Connector sweep: Gold/platinum connectors declare
momentum_capabilities; audit withpnpm momentum:capability-audit.
Reference
| Topic | Location |
|---|---|
| Quickstart | docs/runbooks/momentum-quickstart.md |
| Getting started guide | docs/guides/momentum-getting-started.md |
| MCP tools | docs/guides/momentum-mcp-tools.md |
| Connector authoring | docs/runbooks/momentum-connector-authoring.md |
| Template library | packages/momentum/src/templates/ |
| API routes | apps/api/src/routes/momentum/index.ts |