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.

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