Convex
Recommended architecture for running Crux inside Convex actions, Agent threads, storage, flows, swarms, and devtools.
Run Crux agents inside Convex: define prompts, memory, and tools once, then execute them from Convex actions, Convex Agent threads, and durable flows with full trace continuity. Core primitives stay in @use-crux/core; Convex storage adapters, function wrappers, and Agent integration come from @use-crux/convex. Start with Setup to install the component and create the shared store helper.
Recommended rule: define prompts, contexts, memory, workspaces, skills,
blackboards, and immediate compositions with @use-crux/core; run Convex
actions, Convex Agent tools, durable flows, experimental cross-action swarms,
and observability flushing through @use-crux/convex.
Why Convex Needs Its Own Boundaries
Convex is a serverless runtime: actions can run in fresh workers, scheduled work resumes later, and AsyncLocalStorage does not survive ctx.runAction() or scheduler boundaries. Crux therefore treats Convex as infrastructure, not as an adapter, and provides Crux-aware function wrappers that carry run/span context across those boundaries.
Recommended Architecture
convex/
convex.config.ts # installs @use-crux/convex component
crux/
storage.ts # convexRecordStore()/convexStorage() helpers
prompts/
index.ts # prompt/context/agent definitions
agent/
chat.ts # @use-crux/convex/server action entrypoints
tools.ts # @use-crux/convex/agent createTool()/wrapConvexTool()
workflows/
writerFlow.ts # @use-crux/convex/server flow() handles
swarm.ts # @use-crux/convex/swarm experimental cross-action swarmsBest Practices
| Do | Why |
|---|---|
Use action() / internalAction() from @use-crux/convex/server for AI runtime boundaries | Restores trace context, provides ctx.crux, and flushes before workers exit |
Use ctx.crux.runAction(label, ref, args) for child AI work | Preserves parent/child relations across worker boundaries |
| Keep app-specific mutation helpers in your app | Table names, tenancy, and auth are application policy |
Use convexRecordStore() or convexStorage() for Crux data records | Component-backed records for memory, blackboards, plans, prompt cache, workspace metadata, and React reads |
Use @use-crux/convex/agent with Convex Agent | Tool calls get readable names and nested work inherits the active span |
Use flow() for suspend/resume; treat createComponentSwarm() as experimental | Compositions execute immediately; durable swarm semantics are still being explored |
| Avoid | Why |
|---|---|
Raw ctx.runAction() for related AI work | It loses Crux run/span context |
Publicly exporting .action when auth is required | Wrap .handler in your own public action and do tenant checks first |
| Treating prompt/context/memory resolution as Convex-only | Those are portable core primitives |
| Creating new Convex-specific versions of every composition | Immediate compositions work inside an active Crux-aware boundary |
Pages
Setup
Install the component and create the shared store helper.
Function boundaries
Use Crux-aware action, query, mutation, scheduler, and runAction helpers.
Storage, memory, workspaces
Use Convex storage adapters, memory blocks, blackboards, and Convex file storage.
Agent, tools, skills
Integrate Convex Agent, Crux tools, blackboards, and skills.
Flows
Build durable Convex-aware flows with .action, .handler, .args, and .signal().
Swarms
Run one swarm turn per Convex action with component persistence.
Observability
Connect devtools, flush actions, and preserve trace continuity.
Recipes
Recommended patterns and anti-patterns for common Convex situations.