Cruxible Core

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-core.git
cd cruxible-core
uv sync --extra server --extra mcp
source .venv/bin/activate

CRUXIBLE_SERVER_STATE_DIR="$HOME/.cruxible/server" cruxible server start

The daemon is local-only by default and binds to 127.0.0.1:8100. Initialize
an instance from a kit and run your first query:

cruxible --server-url http://127.0.0.1:8100 init --kit agent-operation

cruxible --server-url http://127.0.0.1:8100 --instance-id <instance_id> \
  query run actor_work_queue --param actor_id=alice --json

The returned instance_id is the handle every surface (CLI, MCP tools, HTTP
client, UI) uses from then on. The same query surface is available from
Python:

from cruxible_client import CruxibleClient

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

For auth, hardening, and daemon operations, 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:

Write mode	Use it for	What happens
Direct write	Asserting hard state — imports, deterministic relationships, source evidence	Live and queryable at once, with evidence when supplied, but unreviewed until a governed process approves it
Governed proposal	Judgment calls — uncertain or interpretive relationships	Candidates are grouped under one thesis with signal evidence and routed to a human or auto-resolution policy; approval writes accepted state with provenance, rejection records why

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 · RAG · vector memory	Cruxible
A claim is just text — no source, no review state	Claims carry provenance and review state; evidence-gated writes refuse references that don't dereference to content-hash-verified source chunks
Anything can be edited; nothing enforces what may change	Writes pass typed validation, guards, review, and lifecycle rules
Retrieval returns similar chunks; it can't follow exact links	Multi-hop traversal over typed relationships, with visibility rules applied at every hop
Counts and rollups are approximate summaries	Exact, repeatable counts and joins as deterministic workflow steps
Each read is fresh and can disagree with the last	One accepted state — the same answer for every agent and app
A correction is just more text — nothing ties it to the claim it corrects	Feedback and outcomes attach to the specific claim, decision, or workflow result as typed, queryable signal
Static text that doesn't improve from use	Claims mature from proposed to accepted; the ontology iterates with use
A better model reads better, but can't certify its own output	Guarantees come from a deterministic layer outside the model

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:

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.
Governed proposals. Uncertain relationships are proposed, reviewed, and
accepted or rejected with provenance; resolution paths carry an explicit
trust status.
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 Core
  deterministic runtime, no LLM inside
          |
          v
state.db
  graph state, receipts, traces, groups, feedback, outcomes, decisions,
  snapshots, source artifacts

Kits

Kit	Kind	Status	What it models
agent-operation	Agent operating state	ready	Work items, review requests, decisions, risks, open questions, state notes, actors, lifecycle, and dependency context.
kev-reference	Domain reference state	ready	Public known-exploited vulnerability reference data.
kev-triage	Domain overlay state	ready	Local asset exposure, service impact, controls, incidents, findings, remediation, and governed vulnerability triage.
supply-chain-blast-radius	Domain state	in_progress	Suppliers, components, assemblies, products, shipments, and incident blast radius.
case-law-monitoring	Domain state	in_progress	Matter-centered case-law monitoring and authority impact.

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-core 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"
      }
    }
  }
}

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 Core 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