Show HN: Cruxible – Open-source governed truth layer for AI agents

Uh oh!

There was an error while loading. Please reload this page.

Notifications You must be signed in to change notification settings

Fork 0

Star 6

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

172 Commits

172 Commits

.github/workflows

.github/workflows

assets

assets

deploy

deploy

docs

docs

examples/wiki-import-demo

examples/wiki-import-demo

kits

kits

packages/cruxible-client

packages/cruxible-client

packaging/cruxible-core-stub

packaging/cruxible-core-stub

scripts

scripts

skills

skills

src/cruxible_core

src/cruxible_core

tests

tests

.gitignore

.gitignore

AGENTS.md

AGENTS.md

CHANGELOG.md

CHANGELOG.md

CODE_OF_CONDUCT.md

CODE_OF_CONDUCT.md

CONTRIBUTING.md

CONTRIBUTING.md

LICENSE

LICENSE

NOTICE

NOTICE

README.md

README.md

SECURITY.md

SECURITY.md

THIRD_PARTY_DATA.md

THIRD_PARTY_DATA.md

context7.json

context7.json

glama.json

glama.json

pyproject.toml

pyproject.toml

server.json

server.json

uv.lock

uv.lock

Repository files navigation

Cruxible is hard state for AI agents — a typed, verifiable state layer that teams of agents and humans operate together. Work compounds into a record of what you've determined to be true: every claim reviewed and linked to its evidence. When the expensive question arrives (which assets are exposed? what breaks downstream? is this authority still good law?), the answer is computed over established truth, not guessed from a pile of context.

You model your domain in a Terraform-like config: entity and relationship types, deterministic workflows, write rules. The runtime enforces it.

State enters deterministically. Exports and tables from real systems are pinned as artifacts and matched row by row into proposals; model judgment is injected only where your pinned domain logic can't decide.

Writes are governed. Governed relationships can only be written through a proposal flow that requires declared evidence, auto-resolves only under trust rules you set, and routes everything else to human review. Every accepted claim is attributed and carries a receipt.

The model is executable. Recurring procedures are declared workflows in the same config: previewed before they apply, locked to the exact provider code and artifacts they compile against, replayable from receipts. State accumulates as the exhaust of governed work, and the model improves iteratively: feedback and outcomes are recorded in state, and the config evolves like code.

Reads are reproducible. Same query, same state, same result, with a receipt explaining how it was derived. Queries express structure that retrieval can't: multi-hop traversals, review status, staleness against cited sources.

The core is deterministic. No LLM inside, no hidden API calls. It works with any agent or harness, points at your existing systems, and mints into state only the claims worth coordinating around.

Get Started

pip install cruxible

Model your own domain: hand your agent the authoring skills in skills/ (prepare-data → create-state → review-state) with your exports (wiki-to-state converts an existing CLAUDE.md pile or Obsidian vault), or start from Modeling State and the config template.

Or run the demo — a seeded supply-chain world, ~3 minutes, no tokens (sandbox writes attribute to a built-in operator identity):

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

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

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

Why Not Markdown, RAG, Or Vector Memory?

Markdown, retrieval, and vector memory hand a model raw text, so every session it reconstructs what's true from scratch. For drafts, exploration, and one-off questions, that's fine — but for the claims that are recurring, shared, and expensive to get wrong, every fresh read re-rolls the reconstruction, and 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, governed state, read instead of 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

Freshness is unknowable: nothing says which chunks have gone stale Claims cite dated, content-hashed sources; staleness is a queryable property, not a vibe

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, and Cruxible itself cites markdown chunks as source evidence. Version control narrows the gap less than it seems: git reviews the diff, not the claim — nothing types what a changed line asserts or refuses an edit that drops its evidence. And nobody hand-tends this state: it accumulates as the exhaust of governed work, not as a wiki someone has to maintain. If you already have the wiki (a pile of CLAUDE.md files, a memory bank, an Obsidian vault), the wiki-to-state skill converts it: pages become pinned evidence, an agent proposes the typed claims, and you review what gets minted. The wiki survives as the source of record; the graph becomes accountable to it.

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 the enum vocabularies, guards, proposal routing, workflows, and providers, so a domain's model, rules, and procedures ship together as one versioned, composable kit.

Nobody types this state in by hand: it enters through the pathways the config declares, and different state earns different treatment.

Hard facts are deterministic ingest. A BOM workflow pins the export as an artifact and matches its rows into suppliers, components, and supply edges, previewed before it commits:

cruxible run --workflow ingest_bom --input-file ./exports/bom-2026-07.csv # preview cruxible apply --workflow ingest_bom --from-last-preview # commit

incident_impacts_supplier is a judgment call, so it is governed: nothing may write it directly, not even a workflow. The incident feed's workflow records the incidents themselves as hard facts, but the impact edges it can only propose. Those candidates land in a review group, each carrying the signals and evidence that matched it:

cruxible propose --workflow propose_incident_impacts --input-file ./exports/incidents.json

The judgment itself stays with a human, or with an agent when the trust rules you declared allow it. Approval is what mints the edges into accepted state: attributed, rationale on record.

cruxible group list --status pending_review cruxible group resolve --group GRP-7f3a --action approve \ --rationale "Confirmed: fab flooding halts board shipments" \ --expected-pending-version 1 # pins the decision to the state the reviewer saw

With the facts ingested and the impact claim approved, an agent (or app) can ask for the blast radius of the 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.

This is what a pending review group looks like in the inspection UI: the signal matrix, each proposed edge with the evidence that matched it, and the provenance rail tying the proposal back to its workflow, receipts, and provider traces.

Governance

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

Write mode Use it for What happens

Direct write Ass

[truncated for AI cost control]