# Cruxible Core

> Hard, verifiable state layer for AI agents

- **Type:** MCP server
- **Install:** `agentstack add mcp-cruxible-ai-cruxible-core`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [cruxible-ai](https://agentstack.voostack.com/s/cruxible-ai)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [cruxible-ai](https://github.com/cruxible-ai)
- **Source:** https://github.com/cruxible-ai/cruxible

## Install

```sh
agentstack add mcp-cruxible-ai-cruxible-core
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Cruxible

[](https://pypi.org/project/cruxible/)
[](https://python.org)
[](https://github.com/cruxible-ai/cruxible/blob/main/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.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:

```bash
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:

```bash
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 
```

`--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:

```bash
cruxible credential claim-bootstrap --secret-file "$HOME/.cruxible/bootstrap.secret"
export CRUXIBLE_SERVER_BEARER_TOKEN=   # printed once by the claim

cruxible credential mint --label claude --mode graph_write
export CRUXIBLE_SERVER_BEARER_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:

```bash
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):

```python
from cruxible_client import CruxibleClient

with CruxibleClient(base_url="http://127.0.0.1:8100", token="") as client:
    result = client.query("", "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](https://github.com/cruxible-ai/cruxible/blob/main/docs/runtime-auth-and-agent-roles.md)).
For the full bootstrap flow, permission tiers, and hardening, see the
[Quickstart](https://github.com/cruxible-ai/cruxible/blob/main/docs/quickstart.md) and
[Runtime Auth And Agent Roles](https://github.com/cruxible-ai/cruxible/blob/main/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
  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 referen

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [cruxible-ai](https://github.com/cruxible-ai)
- **Source:** [cruxible-ai/cruxible](https://github.com/cruxible-ai/cruxible)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-cruxible-ai-cruxible-core
- Seller: https://agentstack.voostack.com/s/cruxible-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.