@claxedo/workgraph

@claxedo/workgraph is a durable place to organize goals, understand what agents are doing, preserve decisions and evidence, and resume work without reconstructing old conversations. Each personal WorkGraph is physically scoped by a trusted (organization, user) tuple derived by the host — the organization supplies the security and Connection boundary, and the WorkGraph remains the user’s personal work structure inside it.

Personal WorkGraph
  └─ Stream
      ├─ Task (Work Item)
      │   └─ Attempt
      └─ Outcome (optional grouping for Tasks)

Streams also hold Work Sources, Decisions, artifacts, external issues, and agent discoveries.

@claxedo/workgraph ships the backend-neutral application service, the HTTP/ordered-change contract, and the SQLite adapter. claxedo-server is the production host: it selects the adapter (Convex for Claxedo Cloud, SQLite for local/self-host), mounts the HTTP router, and injects the service into embedded agent tools, MCP, webhooks, and reconcilers.

Install

npm install @claxedo/workgraph

Quickstart: local SQLite composition

import Database from "better-sqlite3"
import { createSqliteWorkGraphService } from "@claxedo/workgraph"

const database = new Database("./workgraph.db")
const workgraph = createSqliteWorkGraphService({ database }).service

claxedo-server wraps this service with its storage, Connections, and workspace-execution adapters, mounts the standard HTTP router for the app and the standalone MCP, and hands the service directly to local embedded agent tools and background workers. Claxedo Cloud uses the same composition with Convex and hosted execution adapters instead.

Key capabilities

• Tenant-scoped everywhere — every command, query, and cursor is bound to (organization_id, owner_user_id); clients never select a tenant through request data.
• Backend-neutral storage port — domain services depend on an AtomicWorkGraphStore<Commands, Queries> (command/query maps), not a database handle. Convex and SQLite are adapters against the same port.
• Immutable Work Source revisions — captured text is frozen per revision; a later revision produces a diff-based replan proposal (keep, replace, or fork), never a silent mutation of confirmed work.
• Candidate admission — GitHub, Linear, and Jira issues (via @claxedo/connections-backed Connections) and independent agent-session discoveries surface as tenant-scoped candidates; Add to WorkGraph freezes one immutable Work Source revision and its admission proposal for compare-and-set confirmation.
• Execution inheritance — config resolves through WorkGraph defaults → Stream → optional Outcome → Task → Attempt snapshot; each executable Stream owns one worktree or cloud VM envelope.
• Ordered change streams — a WorkGraphChange cursor contract (with a distinct SnapshotResumeCursor for paginated snapshots) lets clients reconnect and converge without polling full state.

Persistence

Composition	Default adapter
Claxedo Cloud	Convex
Local Claxedo and single-node self-host	SQLite
OSS custom deployment	User-supplied conforming adapter

SQLite is an adapter, not the architecture — the package exposes backend-neutral application services plus explicit SQLite and hosted adapter entry points, and hosts choose the adapter when composing the service.

Custom adapters and conformance

OSS adapters implement the public ports and run the runner-neutral conformance suite:

import { describe, test } from "vitest"
import { workGraphAdapterConformance } from "@claxedo/workgraph/conformance"
import { createWorkGraphService } from "@claxedo/workgraph/hosted"
import { defineAtomicWorkGraphStore } from "@claxedo/workgraph/ports"

const factory = async (input) => {
  const store = defineAtomicWorkGraphStore({
    commands: createCommands(input),
    queries: createQueries(input),
  })
  return { service: createWorkGraphService(store), faults: createFaultControls() }
}

describe("my WorkGraph adapter", () => {
  workGraphAdapterConformance(factory).forEach((testCase) => test(testCase.name, testCase.run))
})

Core conformance version 6 certifies tenant isolation, operation idempotency, compare-and-set writes with append rollback, ordered tenant/Stream change cursors, stable snapshot pagination, snapshot-relevant mutation invalidation, Stream lifecycle validation, immutable Work Source revisions, evidence-backed completion, lease acquisition/renewal/expiry, Attempt runtime recovery, and source-revision replacement fencing. A separate archive conformance version 1 covers tenant-scoped export/restore, cross-tenant and non-empty-target rejection, and malformed/secret-bearing archive rejection. The conformance harness imports neither SQLite nor Convex and runs under any test runner that accepts async test functions.

Public surfaces

@claxedo/workgraph             embedded service, HTTP router, SQLite adapter, connectors
@claxedo/workgraph/contracts   runtime-neutral DTOs and validators
@claxedo/workgraph/domain      browser-safe domain rules
@claxedo/workgraph/hosted      Worker-safe service and router composition
@claxedo/workgraph/matching    runtime-neutral bounded placement helpers
@claxedo/workgraph/ports       public adapter port definitions
@claxedo/workgraph/connectors  GitHub, Linear, and Jira source-issue connectors
@claxedo/workgraph/conformance runner-neutral custom-adapter contract tests

The root entry also exports createWorkGraphHttpRouter (the standard HTTP router claxedo-server mounts for the app and standalone MCP) and the SQLite adapter’s schema init, archive, activity, owner-deletion, intake, webhook intake, attention-acknowledgement, session-intake, source-planning-runtime, and legacy-migration entry points. Production entrypoints compose the current V2 runtime; the retained legacy migration reader is an explicit migration-window input, not an application entrypoint.

Execution capability discovery

GET /api/workgraph/execution-capabilities is the tenant-scoped, side-effect-free catalog WorkGraph Settings reads: one server-attested snapshot with a content revision, observation time, exclusive expiry, supported environments and policy values, the active runtime harness, agents, models, efforts, tools, repository choices, and connected Connection metadata. Catalog lifetime is capped at five minutes; Settings writes and Attempt admission validate the exact tenant, freshness, and selected values against it. POST /api/workgraph/execution-capabilities/refresh is the explicit tenant-authorized operation that may provision or refresh the hosted catalog runtime — WorkGraph Settings itself only ever reads the GET.

Boundaries

• WorkGraph owns personal work structure, candidate admission state, Attempts, Decisions, events, and sync receipts.
• Connections owns provider credentials, refresh, capability grants, and authentication health; WorkGraph stores only the user’s Connection binding, provider identity mapping, filters, and sync receipts.
• Workspace runtimes own files, processes, terminals, worktrees, and cloud VMs that a Stream’s Attempts execute inside.
• The hosted control plane owns identity, team membership, entitlement, and workspace access.

WorkGraph’s Docs v2 adapter seam accepts exact immutable document revisions for Work Sources, but the current legacy Pages authoring surface does not yet invoke it — that journey is not triggerable end to end today. Real Cloud release acceptance (Convex schema/functions → Worker → app, in that order, plus a signed cross-tenant browser journey) is also still pending a configured staging deployment.

Full API

See the README and ARCHITECTURE.md on GitHub for the full ownership model, events/ordered-changes contract, execution and completion flows, and delivery status.

The layer stack, explained

Where WorkGraph sits relative to Connections and the workspace runtime.