cruxible-core

<p align="center"> <a href="https://cruxible.ai"> <img src="assets/cruxible_logo.png" alt="Cruxible" width="400"> </a> </p> # Cruxible Core [](https://pypi.org/project/cruxible-core/) [](https://python.org) [](LICENSE) **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): ```bash 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: ```bash 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: ```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](docs/quickstart.md) and [Runtime Auth And Agent Roles](docs/runtime-auth-and-agent-roles.md). ## What A Governed Domain Looks Like A minimal slice of a supply-chain ontology, as authored in a kit config: ```yaml 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: ```bash 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. ```json { "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**: ```bash 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 `SubjectRef`s across instances) compose them into one queryable graph: ```mermaid 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 ```text 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](kits/agent-operation/) | Agent operating state | ready | Work items, review requests, decisions, risks, open questions, state notes, actors, lifecycle, and dependency context. | | [kev-reference](kits/kev-reference/) | Domain reference state | ready | Public known-exploited vulnerability reference data. | | [kev-triage](kits/kev-triage/) | Domain overlay state | ready | Local asset exposure, service impact, controls, incidents, findings, remediation, and governed vulnerability triage. | | [supply-chain-blast-radius](kits/supply-chain-blast-radius/) | Domain state | in_progress | Suppliers, components, assemblies, products, shipments, and incident blast radius. | | [case-law-monitoring](kits/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. ```bash pip install cruxible-client ``` MCP example: ```json { "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](docs/isolated-deployment.md). ## Documentation **Getting started** - [Quickstart](docs/quickstart.md) — install to first query - [Concepts](docs/concepts.md) — architecture and primitives **Modeling and authoring** - [Modeling State](docs/modeling-state.md) — designing an ontology (entities, relationships, gates vs flags) - [Config Reference](docs/config-reference.md) — the YAML config schema - [Kit Authoring](docs/kit-authoring.md) — kit manifest, structure, and packaging - [Kit Walkthroughs](docs/kit-walkthroughs.md) — building standalone and overlay kits - [Common Providers And Dataflow Steps](docs/common-providers.md) — provider and workflow building blocks **Reference** - [CLI Reference](docs/cli-reference.md) — terminal commands - [MCP Tools Reference](docs/mcp-tools.md) — agent tool surface - [AI Agent Guide](docs/for-ai-agents.md) — orchestration patterns **Operating and deploying** - [Local State And Backups](docs/local-state-and-backups.md) — SQLite, daemon state, and portability - [Runtime Auth And Agent Roles](docs/runtime-auth-and-agent-roles.md) — credentials, permission tiers, and bootstrap - [State Resolution And Maintenance](docs/state-resolution-and-maintenance.md) — proposal resolution, trust grading, and maintenance signals - [Isolated Deployment](docs/isolated-deployment.md) — running the daemon with only the client/MCP surface exposed - [Hosted Runtime Image](docs/hosted-runtime-image.md) — the runtime container image **Guides** - [Skill Classification At Scale](docs/skill-classification-at-scale.md) — a worked governed-classification agent playbook ## Technology Cruxible Core uses [Pydantic](https://docs.pydantic.dev/) for validation, [NetworkX](https://networkx.org/) for in-memory graph operations, [Polars](https://pola.rs/) for data operations, [SQLite](https://sqlite.org/) for local durable state, [FastAPI](https://fastapi.tiangolo.com/) for the daemon, and [FastMCP](https://github.com/jlowin/fastmcp) for MCP tools. ## License Apache 2.0 <!-- mcp-name: io.github.cruxible-ai/cruxible-core -->