Cruxible

Cruxible is hard state for AI agents.

Typed, governed, durable state that outlives any single model, session, or context window.

Agents re-derive what's true from prompts, retrieval, and chat history, and no amount of context engineering makes that reconstruction reliable. A better model reads better, but it cannot certify its own output. Cruxible's answer is to model the domain instead of engineering the context: the durable slice of what's true becomes typed entities and relationships with lifecycle and review status, and agents and humans operate on that shared state instead of reconstructing it.

The same move applies to the work itself. Reads are deterministic queries over typed relationships, not retrieval. Recurring procedures are declared workflows — previewed, locked, replayable — not agent loops gluing tool calls together. The model is invoked only where judgment is actually needed, and what it proposes passes guards and review, with a human in the loop where the stakes warrant it, and leaves a receipt on the way in.

The core is deterministic: no LLM inside, no hidden API calls. It works with any agent or harness, and rather than replacing your source systems, it points at them, cites specific records or chunks, and mints into state only the claims worth coordinating around.

Get Started

For 0.2, install from a clone so the bundled starter kits resolve from the checkout (versioned OCI kit images are coming; until then the checkout is the canonical path):

git clone https://github.com/cruxible-ai/cruxible.git
cd cruxible
uv sync --extra server --extra mcp
source .venv/bin/activate

Start the daemon with runtime auth on. It binds to 127.0.0.1:8100 (pass --port if 8100 is taken), generates a one-time bootstrap secret, and writes it to a 0600 file:

CRUXIBLE_SERVER_AUTH=true CRUXIBLE_SERVER_STATE_DIR="$HOME/.cruxible/server" \
  cruxible server start --bootstrap-secret-file "$HOME/.cruxible/bootstrap.secret"

From a second shell, initialize the agent-operation kit — durable operating state for a team of agents (work items, reviews, decisions, risks, actors) — and remember the connection so later commands need no flags:

export CRUXIBLE_SERVER_BEARER_TOKEN="$(cat "$HOME/.cruxible/bootstrap.secret")"
cruxible --server-url http://127.0.0.1:8100 init --kit agent-operation --bootstrap
cruxible context connect --server-url http://127.0.0.1:8100 --instance-id <instance-id>

--kit is repeatable to compose overlay kits onto a base at init, e.g. cruxible init --kit agent-operation --kit project-domain.

Claim the admin credential, then mint one for your first agent. Minting is what creates the agent's identity in state: the kit's Actor type is auth-managed, so the Actor entity materializes from the mint, and no other write path can create one — an agent roster you can trust because it cannot be typo'd into existence:

cruxible credential claim-bootstrap --secret-file "$HOME/.cruxible/bootstrap.secret"
export CRUXIBLE_SERVER_BEARER_TOKEN=<admin-token>   # printed once by the claim

cruxible credential mint --label claude --mode graph_write
export CRUXIBLE_SERVER_BEARER_TOKEN=<claude-token>  # act as the agent from here

Give the agent work and read its queue back. Writes are validated against the kit's ontology, attributed to the token's actor, and receipted:

cruxible entity add WorkItem wi-first-slice \
  --set title="Model the first slice of our domain" \
  --set type=research --set status=active --set priority=high

cruxible relationship add work_item_owned_by_actor WorkItem wi-first-slice Actor claude

cruxible query run actor_work_queue --param actor_id=claude --json

The same surface is available from Python (and MCP, below):

from cruxible_client import CruxibleClient

with CruxibleClient(base_url="http://127.0.0.1:8100", token="<claude-token>") as client:
    result = client.query("<instance-id>", "actor_work_queue", {"actor_id": "claude"})
    for item in result.items:
        print(item)

Auth is on in this path because agent identity lives in the auth layer. To run open (no tokens) for a local experiment, start the daemon without CRUXIBLE_SERVER_AUTH — kits that declare auth-managed identity, like agent-operation, refuse to load with an error naming exactly which config keys to remove, rather than silently degrading.

One thing to know before moving on: once its bootstrap secret is claimed, an auth-on daemon cannot create additional instances in that run — the quickstart's init commands need a fresh daemon started alongside this one (see Runtime Auth And Agent Roles). For the full bootstrap flow, permission tiers, and hardening, see the Quickstart and Runtime Auth And Agent Roles.

Related MCP server: decide

What A Governed Domain Looks Like

A minimal slice of a supply-chain ontology, as authored in a kit config:

entity_types:
  Supplier:
    properties:
      supplier_id: { type: string, primary_key: true }
      name: { type: string, indexed: true }
      primary_geography: { type: string, optional: true }
  Component:
    properties:
      component_id: { type: string, primary_key: true }
      name: { type: string, indexed: true }
      criticality: { type: string, optional: true, enum_ref: criticality }
  Incident:
    properties:
      incident_id: { type: string, primary_key: true }
      title: { type: string, indexed: true }
      severity: { type: string, optional: true, enum_ref: incident_severity }

relationships:
  - name: supplier_supplies_component
    from: Supplier
    to: Component
  # Governed judgment: an incident materially impacts a supplier.
  - name: incident_impacts_supplier
    from: Incident
    to: Supplier

named_queries:
  # Blast radius: from an incident, traverse impacted suppliers to the
  # components they supply.
  components_exposed_by_incident:
    mode: traversal
    entry_point: Incident
    returns: Component
    traversal:
      - relationship: incident_impacts_supplier
        direction: outgoing
      - relationship: supplier_supplies_component
        direction: outgoing

The ontology is only part of the config: the same file declares guards, proposal routing, workflows, and providers, so a domain's model, rules, and procedures ship together as one versioned, composable kit.

An agent (or app) can now ask for the blast radius of an incident (the components exposed through its impacted suppliers) without scanning spreadsheets or tracing the bill of materials by hand:

cruxible query run components_exposed_by_incident \
  --param incident_id=INC-42 \
  --json

Results come back with a receipt: the deterministic path from query parameters to traversed edges to returned rows.

{
  "items": [
    { "entity_type": "Component", "entity_id": "component-main-board" }
  ],
  "receipt_id": "RCP-...",
  "receipt": {
    "operation_type": "query",
    "query_name": "components_exposed_by_incident",
    "parameters": { "incident_id": "INC-42" },
    "nodes": [
      { "node_type": "query", "detail": { "entry_point": "Incident" } },
      { "node_type": "edge_traversal", "relationship": "incident_impacts_supplier" },
      { "node_type": "edge_traversal", "relationship": "supplier_supplies_component" },
      { "node_type": "result", "entity_type": "Component", "entity_id": "component-main-board" }
    ]
  }
}

Receipts are not logs — they are typed evidence graphs. Mutation receipts record exactly what a write changed, and governed edges carry a reference back to the receipt of the operation that created them.

Governance

Cruxible separates writing state from accepting it. State enters one of two ways:

Guards are declared in config and enforced at a single write chokepoint. A relationship type can refuse direct writes entirely; a work item can be blocked from closing until an approved review is linked; a write can be required to co-create a linked entity in the same unit of work; a claim can be required to carry source evidence. Evidence requirements are enforced, not decorative — the write is refused unless every reference dereferences to a registered source chunk whose content hash matches.

Workflows And Pinned Providers

Workflows orchestrate reads, providers, shaping, and writes as one declared, reproducible procedure. Providers are the building blocks workflows call — deterministic transforms and data loaders in Python, over HTTP, or as commands. They are pinned, not trusted. The kit lockfile (cruxible.lock.yaml) records each provider's version, content digest, and declared side effects, and every call leaves an execution trace, so runs replay deterministically.

Canonical workflows are preview-first:

cruxible run --workflow build_local_state    # executes against a clone, returns an apply digest
cruxible apply --workflow build_local_state --from-last-preview

run never touches live state. apply re-verifies the preview's digest against the current config, lockfile, and head snapshot before committing. If anything shifted underneath, it refuses. Workflows that produce governed proposals run through cruxible propose and land in review instead of in live state.

Declare → preview → apply, with a receipt at every step.

Why Not Markdown, RAG, Or Vector Memory?

Markdown, retrieval, and vector memory give a model text to read, so every session it reconstructs what's true from scratch. Cruxible persists it as typed, governed state — read, not reconstructed. What changes:

Markdown and retrieval remain the right tools for most text (drafts, exploration, one-off questions), and Cruxible itself cites markdown chunks as source evidence. The table is about the durable slice: claims that are recurring, shared, and expensive to get wrong, where re-reading text re-pays the reconstruction cost every session and re-rolls the risk with every fresh read.

Domain State And Operating State

Cruxible models two kinds of state, strongest together.

Domain state is the durable model of the world an agent reasons about — assets, vulnerabilities, suppliers, products, cases, controls, policies, risks. It answers what is true, proposed, reviewed, or constrained. Which assets are exposed to a known exploited vulnerability? Which supplier incident affects which products and shipments?

Agent operating state is the durable coordination layer for the work itself — work items, review requests, decisions, open questions, risks, actors, dependencies, lineage. It tracks what's active or blocked, why, who reviewed it, and what changed.

A domain kit models the thing being worked on; an operating-state kit tracks the work, decisions, and reviews around it. Typed operation-to-domain edges (or SubjectRefs across instances) compose them into one queryable graph:

flowchart LR
  subgraph KEV["KEV domain state"]
    Asset["Asset: ASSET-42"]
    Product["Product: Apache HTTP Server"]
    CVE["Vulnerability: CVE-2021-41773"]
  end

  subgraph Ops["Agent operating layer"]
    Owner["Actor: Agent A"]
    Reviewer["Actor: human reviewer"]
    Work["WorkItem: patch ASSET-42"]
    Review["ReviewRequest: verify remediation"]
    Decision["Decision: emergency patch window"]
    Risk["Risk: exposed to active exploit"]
  end

  Asset -- "runs" --> Product
  CVE -- "affects" --> Product
  Work -- "targets" --> Asset
  Work -- "mitigates" --> Risk
  Risk -- "attaches to" --> CVE
  Decision -- "constrains" --> Work
  Work -- "owned by" --> Owner
  Review -- "reviews" --> Work
  Review -- "requested by" --> Owner
  Review -- "assigned to" --> Reviewer

State That Compounds

Knowledge shouldn't be wiped out by a context refresh, a model swap, or a handoff. Three loops make the state improve with use:

1. Feedback and outcomes. Corrections, missing context, and policy gaps are recorded as feedback; outcomes record whether a decision or workflow result was later correct, incorrect, partial, or unknown. Repeated bad outcomes generate trust-demotion suggestions on the paths that produced them.

2. Governed proposals. Uncertain relationships are proposed, reviewed, and accepted or rejected with provenance; resolution paths carry an explicit trust status.

3. Config iteration. The ontology itself is refined as it's used (new entity types, relationships, guards, and queries), so the model of the domain matures alongside the data.

The model can change: swap vendors, upgrade, run several at once. What compounds belongs to you. State, evidence, review history, feedback, outcomes, and the ontology itself accumulate in a database you own, portable down to a single file, not in a vendor's weights or a platform's memory. The work agents do becomes your asset.

How It Fits

AI agents and humans
  write configs, review proposals, run workflows, record outcomes
          |
          v
CLI / HTTP client / MCP tools
  thin surfaces over the service layer
          |
          v
Cruxible
  deterministic runtime, no LLM inside
          |
          v
state.db
  graph state, receipts, traces, groups, feedback, outcomes, decisions,
  snapshots, source artifacts

Kits

A kit packages an ontology with its governance, queries, workflows, and providers as one versioned, composable unit.

Start with agent-operation — the operating state layer for a team of agents, and the kit Cruxible is developed with. It is domain-agnostic: work items, review requests, decisions, risks, open questions, and actors apply whether your agents write code, run research, or manage a pipeline. Actors are auth-managed, review gates are enforced at the write chokepoint (a work item cannot close without an approved review), and every agent's writes are attributed to its token.

The KEV pair is the depth proof for domain state: a public known-exploited-vulnerability reference state, plus a governed overlay where deterministic ingest, governed proposals (which assets run which products), and review workflows run end to end on real data.

Standalone kits can define a full state model. Overlay kits can extend an upstream state model with local state, governed proposals, and local workflows.

Status — ready kits ship working providers (KEV also ships public reference data), so their workflows execute end to end. in_progress means the ontology, governance, named queries, and feedback/outcome loops are complete and validated, but the data-ingest and assessment providers are placeholders — implement them or wire your own data before running the workflows.

Agent Setup

For agents, prefer a split environment:

• Cruxible runs in a daemon/runtime environment.

• The agent environment installs cruxible-client or uses MCP.

• CRUXIBLE_REQUIRE_SERVER=1 keeps the agent on the daemon path.

• CRUXIBLE_SERVER_STATE_DIR lives outside the agent's writable workspace.

pip install cruxible-client

MCP example:

{
  "mcpServers": {
    "cruxible": {
      "command": "cruxible-mcp",
      "env": {
        "CRUXIBLE_MODE": "governed_write",
        "CRUXIBLE_SERVER_URL": "http://127.0.0.1:8100",
        "CRUXIBLE_SERVER_BEARER_TOKEN": "<agent-token>"
      }
    }
  }
}

Local permission modes are a practical hardening layer, not full sandboxing. If trust levels matter, keep the daemon state outside the agent workspace and expose only the client, HTTP, or MCP surface. See Isolated Deployment.

Documentation

Getting started

• Quickstart — install to first query

• Concepts — architecture and primitives

Modeling and authoring

• Modeling State — designing an ontology (entities, relationships, gates vs flags)

• Config Reference — the YAML config schema

• Kit Authoring — kit manifest, structure, and packaging

• Kit Walkthroughs — building standalone and overlay kits

• Common Providers And Dataflow Steps — provider and workflow building blocks

Reference

• CLI Reference — terminal commands

• MCP Tools Reference — agent tool surface

• AI Agent Guide — orchestration patterns

Operating and deploying

• Local State And Backups — SQLite, daemon state, and portability

• Runtime Auth And Agent Roles — credentials, permission tiers, and bootstrap

• State Resolution And Maintenance — proposal resolution, trust grading, and maintenance signals

• Isolated Deployment — running the daemon with only the client/MCP surface exposed

• Hosted Runtime Image — the runtime container image

Guides

• Skill Classification At Scale — a worked governed-classification agent playbook

Technology

Cruxible uses Pydantic for validation, NetworkX for in-memory graph operations, Polars for data operations, SQLite for local durable state, FastAPI for the daemon, and FastMCP for MCP tools.

License

Apache 2.0