Cruxible

cruxible.ai · quickstart · docs · kits · skills

Cruxible is a governed state engine for AI agents. It turns a YAML ontology into a typed knowledge graph with write rules enforced outside the model.

Declare the model and its rules:

hljs language-yaml

entity_types:
  Incident:
    id: incident_id
    properties:
      title: string indexed
  Supplier:
    id: supplier_id
    properties:
      name: string indexed

relationships:
  - incident_impacts_supplier: Incident -> Supplier
    write_policy: proposal_only        # judgment call: enters only through review

named_queries:
  incident_impacted_suppliers:
    mode: traversal
    entry_point: Incident
    returns: Supplier
    traversal:
      - relationship: incident_impacts_supplier
        direction: outgoing

Agents write; the rules run, not the prompt. The refused write, the review that admits the judgment, and the receipted answer:

hljs language-diff

  $ cruxible relationship add incident_impacts_supplier \
      Incident INC-TW-RAIL-2026-07 Supplier S-CN-DG-HARNESS
- Error: DirectWriteRefusedError: Direct write to relationship
- 'incident_impacts_supplier' is refused (write_policy=proposal_only).
- Use 'group propose' to stage a governed proposal. (receipt: RCP-…)

  $ cruxible propose --workflow propose_incident_impacts_supplier
  $ cruxible group resolve --group <GRP-id> --action approve \
      --rationale "Confirmed against supplier geography"

  $ cruxible query run incident_impacted_suppliers \
      --param incident_id=INC-TW-RAIL-2026-07 --json
+ { "items": [ { "entity_type": "Supplier", "entity_id": "S-CN-DG-HARNESS" } ],
+   "receipt_id": "RCP-2f61a90c84d3" }

This repository gates its own releases with Cruxible: a push to main is refused until state pins an approved review (how).

pip install cruxible — the Quickstart goes install to first query; Get Started below runs the seeded demo world in ~3 minutes, with no model calls or API keys.

No LLM inside the engine: Cruxible is a Python daemon with a CLI and MCP server, with state in a SQLite file you own. We call the result hard state: knowledge the rest of your stack can act on without re-checking it. If your team's knowledge currently lives in markdown or a vector store, the comparison section explains exactly what changes.

Start permissive, then tighten claim types where being wrong is expensive, one write_policy line at a time. Authoring skills can draft the ontology from your data; you review and refine it as the domain teaches you what matters. The model gets stricter where experience proves it should, without an ontology team or a rewrite.

Capabilities

Model — the ontology is a versioned YAML config, drafted by your agent

Entity types, relationships, enums, and queries in one Terraform-like config; kits package a model with its rules and procedures, overlay kits compose over an upstream base
Authoring skills draft the model from your exports or an existing wiki; you review instead of author (Modeling State)

Govern — writes are validated, refused, or reviewed; nothing is silent

Per-type write_policy: direct, proposal-only, or mint-only; guards enforce evidence, transitions, and co-writes at one chokepoint (Concepts)
Judgment calls land in review groups carrying their matching evidence; approval mints attributed state with rationale on record
Four cumulative permission tiers per credential; a guard can require the approving actor differs from the creating actor, anchored on receipts (Auth And Agent Roles)

Ingest — deterministic, preview-first, pinned

Sources register as content-hashed artifacts; claims cite into them
Pipelines preview against a clone, then apply re-verifies digests before committing; providers are version- and digest-pinned with execution traces (Providers And Dataflow)

Ask — receipted answers, built for agent read budgets

Named traversal queries (blast radius, downstream impact) with a receipt you can explain; the same state returns the same answer for every agent
Compact/standard profiles, bounded neighborhood reads, and a graph layout cut cold-start read cost by 86% on our benchmark; every read carries a monotonic revision and truncation is always explicit

Operate — one daemon, many doors, state you own

MCP server, CLI, and Python client against the same daemon, credentials, and tiers; agent setup is one MCP config block
Gates hold outside actions (a merge, a deploy) until state agrees; the first shipped kind wires into git pre-push
Snapshots, backups, state publishing, and an inspection UI over a SQLite file, portable as one artifact (Isolated Deployment)

Get Started

hljs language-bash

pip install cruxible

Model your own domain with the authoring skills and Modeling State, or run the demo — a seeded supply-chain world, ~3 minutes, with no model calls or API keys. Sandbox writes attribute to a built-in operator identity:

hljs language-bash

# shell 1 — local sandbox daemon
CRUXIBLE_SERVER_STATE_DIR="$HOME/.cruxible/sandbox" cruxible server start

# shell 2 — kit bundles are fetched from the release and digest-verified
# (agent-operation is the optional agent-ops layer; domain-only works too)
cruxible --server-url http://127.0.0.1:8100 init --kit agent-operation --kit supply-chain-blast-radius
cruxible context connect --server-url http://127.0.0.1:8100 --instance-id <instance-id>

# deterministic ingest: preview, then commit
cruxible run --workflow build_seed_state && cruxible apply --workflow build_seed_state --from-last-preview
cruxible run --workflow ingest_incidents && cruxible apply --workflow ingest_incidents --from-last-preview

# the incident feed can only PROPOSE impact edges; the judgment is yours, on the record
cruxible propose --workflow propose_incident_impacts_supplier
cruxible group list --status pending_review
cruxible group resolve --group <GRP-id> --action approve \
  --rationale "Confirmed against supplier geography" --expected-pending-version 1

# receipted answers through the edges you just admitted
cruxible query run open_incident_impacts --json
cruxible query run incident_impacted_suppliers --param incident_id=INC-TW-RAIL-2026-07 --json

When agents join, identity turns on: restart with CRUXIBLE_SERVER_AUTH=true, claim the bootstrap credential, and mint each agent its own token — every write is attributed. Details, permission tiers, and hardening: Quickstart · Runtime Auth And Agent Roles.

The Rules Run

Cruxible never asks a model to follow the rules, because the rules run as code. A rule declared in config runs at the write chokepoint on every mutation, and there is no code path around the chokepoint.

Prompted	Enforced
"The agent knows an exposure can't be closed while unremediated"	The write chokepoint refuses the transition until the remediation claim, with its evidence, is linked
"The model says these sources support the claim"	The write is refused unless every reference dereferences to a content-hash-verified source chunk
"The agent was told not to accept claims it proposed itself"	The guard compares the acting actor against the creation receipt's recorded actor and refuses, including create-as-accepted
"The agent remembers the ingest procedure"	The workflow is declared, previewed, and locked to pinned providers; every run leaves a receipt

Guards face inward (the write boundary of accepted state); gates face outward (an external action holds until state agrees).

A declared gate, wired into git pre-push

hljs language-yaml

gates:
  merge-review:
    kind: git-pre-push
    entity_type: ReviewRequest
    match_property: change_head
    condition: {status: approved}
    adapter: {branch_pattern: refs/heads/main}

This repository runs on that gate: it refused our own 0.2.2 release push until the review record was corrected in state. We fixed the state, not the hook.

The Full Walkthrough

The deep dive builds one governed truth end to end: a single reviewed judgment lets a query walk a recursive bill of materials and name every exposed shipment five typed hops downstream, with a receipt you can explain.

Cruxible review group page: signal matrix, proposed edges each carrying matching evidence, and a provenance rail with workflow, receipts, and provider traces

The screenshot is the review seat in the inspection UI: each proposed edge carries the evidence that matched it, with a provenance rail back to workflows, receipts, and traces.

Why Not Markdown, RAG, Or Vector Memory?

We spent fifty years keeping the facts that matter in systems with schemas, constraints, and transactions — then handed agents piles of markdown, because prose was the only interface they spoke. What changes:

Markdown · RAG · vector memory	Cruxible
A claim is prose; nothing refuses one without a source	Evidence-gated writes refuse references that don't verify against content-hashed sources
Edits are reviewed as diffs, not claims	Writes pass typed validation, guards, and review
Links live in prose, re-inferred on every read	Typed edges, traversed multi-hop, visibility rules at every hop
A rollup is a one-off summary	Counts and joins are deterministic, receipted, re-runnable
No record of which answer was settled on	One accepted state; the same query returns the same answer for every agent
No record of when a source was captured	Sources are dated and hashed; staleness is queryable
A correction is just more text	Feedback attaches to the exact claim; claims mature from proposed to accepted
A better model reads the pile better	It can't read what was never written; the record and its derivations don't move when you swap models

If the wiki already exists (a team wiki, an Obsidian vault), the wiki-to-state skill converts it: pages become pinned evidence, an agent proposes the typed claims, you review what gets minted.

Kits

A kit packages an ontology with its governance, queries, workflows, and providers as one versioned, composable unit; per-kit guides run each end to end.

Kit	Kind	What it models
agent-operation	Agent operating state	Work items, review requests, decisions, risks, open questions, state notes, actors, lifecycle, and dependency context.
project-domain	Domain overlay state	Roadmap items, milestones, release lines, and product areas composed over the agent-operation base — the project state Cruxible itself runs on.
agent-release	Domain overlay state	Agent systems, versions, eval suites and runs, with governed certification and promotion gates.
kev-reference	Domain reference state	Public known-exploited vulnerability reference data. Consumed as a published state release (`state create-overlay`); init the kit itself only to build offline or publish your own.
kev-triage	Domain overlay state	Local asset exposure, service impact, controls, incidents, findings, remediation, and governed vulnerability triage.
supply-chain-blast-radius	Domain state	Suppliers, components, assemblies, products, shipments, and incident blast radius.
case-law-monitoring	Domain state	Matter-centered case-law monitoring and authority impact.

Documentation

Quickstart — install to first query
Concepts — architecture and primitives
Deep Dive — a governed domain end to end
Modeling State — designing an ontology
Config Reference — the YAML config schema
CLI Reference · MCP Tools · AI Agent Guide
Kit guides — KEV, supply chain, case law, agent operation — plus deployment, auth, backups, and publishing, all under docs/; agent skills for authoring state from your data

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.

Contributing

Contributions welcome — see CONTRIBUTING.md. If governed agent state is a problem you're working on, star the repo or open an issue with your use case.

License

Apache 2.0

Cruxible

cruxible.ai · quickstart · docs · kits · skills

Cruxible is a governed state engine for AI agents. It turns a YAML ontology into a typed knowledge graph with write rules enforced outside the model.

Declare the model and its rules:

hljs language-yaml

entity_types:
  Incident:
    id: incident_id
    properties:
      title: string indexed
  Supplier:
    id: supplier_id
    properties:
      name: string indexed

relationships:
  - incident_impacts_supplier: Incident -> Supplier
    write_policy: proposal_only        # judgment call: enters only through review

named_queries:
  incident_impacted_suppliers:
    mode: traversal
    entry_point: Incident
    returns: Supplier
    traversal:
      - relationship: incident_impacts_supplier
        direction: outgoing

Agents write; the rules run, not the prompt. The refused write, the review that admits the judgment, and the receipted answer:

hljs language-diff

  $ cruxible relationship add incident_impacts_supplier \
      Incident INC-TW-RAIL-2026-07 Supplier S-CN-DG-HARNESS
- Error: DirectWriteRefusedError: Direct write to relationship
- 'incident_impacts_supplier' is refused (write_policy=proposal_only).
- Use 'group propose' to stage a governed proposal. (receipt: RCP-…)

  $ cruxible propose --workflow propose_incident_impacts_supplier
  $ cruxible group resolve --group <GRP-id> --action approve \
      --rationale "Confirmed against supplier geography"

  $ cruxible query run incident_impacted_suppliers \
      --param incident_id=INC-TW-RAIL-2026-07 --json
+ { "items": [ { "entity_type": "Supplier", "entity_id": "S-CN-DG-HARNESS" } ],
+   "receipt_id": "RCP-2f61a90c84d3" }

This repository gates its own releases with Cruxible: a push to main is refused until state pins an approved review (how).

pip install cruxible — the Quickstart goes install to first query; Get Started below runs the seeded demo world in ~3 minutes, with no model calls or API keys.

Capabilities

Model — the ontology is a versioned YAML config, drafted by your agent

Entity types, relationships, enums, and queries in one Terraform-like config; kits package a model with its rules and procedures, overlay kits compose over an upstream base
Authoring skills draft the model from your exports or an existing wiki; you review instead of author (Modeling State)

Govern — writes are validated, refused, or reviewed; nothing is silent

Per-type write_policy: direct, proposal-only, or mint-only; guards enforce evidence, transitions, and co-writes at one chokepoint (Concepts)
Judgment calls land in review groups carrying their matching evidence; approval mints attributed state with rationale on record
Four cumulative permission tiers per credential; a guard can require the approving actor differs from the creating actor, anchored on receipts (Auth And Agent Roles)

Ingest — deterministic, preview-first, pinned

Sources register as content-hashed artifacts; claims cite into them
Pipelines preview against a clone, then apply re-verifies digests before committing; providers are version- and digest-pinned with execution traces (Providers And Dataflow)

Ask — receipted answers, built for agent read budgets

Named traversal queries (blast radius, downstream impact) with a receipt you can explain; the same state returns the same answer for every agent
Compact/standard profiles, bounded neighborhood reads, and a graph layout cut cold-start read cost by 86% on our benchmark; every read carries a monotonic revision and truncation is always explicit

Operate — one daemon, many doors, state you own

MCP server, CLI, and Python client against the same daemon, credentials, and tiers; agent setup is one MCP config block
Gates hold outside actions (a merge, a deploy) until state agrees; the first shipped kind wires into git pre-push
Snapshots, backups, state publishing, and an inspection UI over a SQLite file, portable as one artifact (Isolated Deployment)

Get Started

hljs language-bash

pip install cruxible

hljs language-bash

# shell 1 — local sandbox daemon
CRUXIBLE_SERVER_STATE_DIR="$HOME/.cruxible/sandbox" cruxible server start

# shell 2 — kit bundles are fetched from the release and digest-verified
# (agent-operation is the optional agent-ops layer; domain-only works too)
cruxible --server-url http://127.0.0.1:8100 init --kit agent-operation --kit supply-chain-blast-radius
cruxible context connect --server-url http://127.0.0.1:8100 --instance-id <instance-id>

# deterministic ingest: preview, then commit
cruxible run --workflow build_seed_state && cruxible apply --workflow build_seed_state --from-last-preview
cruxible run --workflow ingest_incidents && cruxible apply --workflow ingest_incidents --from-last-preview

# the incident feed can only PROPOSE impact edges; the judgment is yours, on the record
cruxible propose --workflow propose_incident_impacts_supplier
cruxible group list --status pending_review
cruxible group resolve --group <GRP-id> --action approve \
  --rationale "Confirmed against supplier geography" --expected-pending-version 1

# receipted answers through the edges you just admitted
cruxible query run open_incident_impacts --json
cruxible query run incident_impacted_suppliers --param incident_id=INC-TW-RAIL-2026-07 --json

The Rules Run

Prompted	Enforced
"The agent knows an exposure can't be closed while unremediated"	The write chokepoint refuses the transition until the remediation claim, with its evidence, is linked
"The model says these sources support the claim"	The write is refused unless every reference dereferences to a content-hash-verified source chunk
"The agent was told not to accept claims it proposed itself"	The guard compares the acting actor against the creation receipt's recorded actor and refuses, including create-as-accepted
"The agent remembers the ingest procedure"	The workflow is declared, previewed, and locked to pinned providers; every run leaves a receipt

Guards face inward (the write boundary of accepted state); gates face outward (an external action holds until state agrees).

A declared gate, wired into git pre-push

hljs language-yaml

gates:
  merge-review:
    kind: git-pre-push
    entity_type: ReviewRequest
    match_property: change_head
    condition: {status: approved}
    adapter: {branch_pattern: refs/heads/main}

This repository runs on that gate: it refused our own 0.2.2 release push until the review record was corrected in state. We fixed the state, not the hook.

The Full Walkthrough

Cruxible review group page: signal matrix, proposed edges each carrying matching evidence, and a provenance rail with workflow, receipts, and provider traces

The screenshot is the review seat in the inspection UI: each proposed edge carries the evidence that matched it, with a provenance rail back to workflows, receipts, and traces.

Why Not Markdown, RAG, Or Vector Memory?

Markdown · RAG · vector memory	Cruxible
A claim is prose; nothing refuses one without a source	Evidence-gated writes refuse references that don't verify against content-hashed sources
Edits are reviewed as diffs, not claims	Writes pass typed validation, guards, and review
Links live in prose, re-inferred on every read	Typed edges, traversed multi-hop, visibility rules at every hop
A rollup is a one-off summary	Counts and joins are deterministic, receipted, re-runnable
No record of which answer was settled on	One accepted state; the same query returns the same answer for every agent
No record of when a source was captured	Sources are dated and hashed; staleness is queryable
A correction is just more text	Feedback attaches to the exact claim; claims mature from proposed to accepted
A better model reads the pile better	It can't read what was never written; the record and its derivations don't move when you swap models

If the wiki already exists (a team wiki, an Obsidian vault), the wiki-to-state skill converts it: pages become pinned evidence, an agent proposes the typed claims, you review what gets minted.

Kits

A kit packages an ontology with its governance, queries, workflows, and providers as one versioned, composable unit; per-kit guides run each end to end.

Kit	Kind	What it models
agent-operation	Agent operating state	Work items, review requests, decisions, risks, open questions, state notes, actors, lifecycle, and dependency context.
project-domain	Domain overlay state	Roadmap items, milestones, release lines, and product areas composed over the agent-operation base — the project state Cruxible itself runs on.
agent-release	Domain overlay state	Agent systems, versions, eval suites and runs, with governed certification and promotion gates.
kev-reference	Domain reference state	Public known-exploited vulnerability reference data. Consumed as a published state release (`state create-overlay`); init the kit itself only to build offline or publish your own.
kev-triage	Domain overlay state	Local asset exposure, service impact, controls, incidents, findings, remediation, and governed vulnerability triage.
supply-chain-blast-radius	Domain state	Suppliers, components, assemblies, products, shipments, and incident blast radius.
case-law-monitoring	Domain state	Matter-centered case-law monitoring and authority impact.

Documentation

Quickstart — install to first query
Concepts — architecture and primitives
Deep Dive — a governed domain end to end
Modeling State — designing an ontology
Config Reference — the YAML config schema
CLI Reference · MCP Tools · AI Agent Guide
Kit guides — KEV, supply chain, case law, agent operation — plus deployment, auth, backups, and publishing, all under docs/; agent skills for authoring state from your data

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.

Contributing

Contributions welcome — see CONTRIBUTING.md. If governed agent state is a problem you're working on, star the repo or open an issue with your use case.

License

Apache 2.0

cruxible

Cruxible

Capabilities

Get Started

The Rules Run

The Full Walkthrough

Why Not Markdown, RAG, Or Vector Memory?

Kits

Documentation

Technology

Contributing

License

Similar Packages

cruxible

Cruxible

Capabilities

Get Started

The Rules Run

The Full Walkthrough

Why Not Markdown, RAG, Or Vector Memory?

Kits

Documentation

Technology

Contributing

License

Similar Packages