# cruxible-core

Deterministic state engine for AI agents. It organizes knowledge in a typed graph, gates unsafe writes with reviews, and tracks outcomes with receipts.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 17
- Author: cruxible-ai
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/cruxible-ai/cruxible
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/cruxible-core

## What it does

Cruxible gives agents a governed environment instead of storing state in unverified chat history. Domain schemas and relationship policies are declared in YAML. When ingestion pipelines run, facts become typed nodes in a graph. If a relationship requires confirmation, direct writes fail immediately, forcing the agent to route changes through a review proposal.

No language models run inside this engine. Every graph query, mutation, and bound procedure executes deterministically. When an action finishes or a state changes, the system issues an explicit receipt identifier for traceability. Teams can pin outcome contracts to check whether actions satisfied their original goals after real-world execution.

Running the server requires Python 3.11+ and `uvx`. Access boundaries rely on `CRUXIBLE_MODE` and `CRUXIBLE_ALLOWED_ROOTS` environment variables.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `CRUXIBLE_MODE`, `CRUXIBLE_ALLOWED_ROOTS` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env CRUXIBLE_MODE=<CRUXIBLE_MODE> --env CRUXIBLE_ALLOWED_ROOTS=<CRUXIBLE_ALLOWED_ROOTS> --transport stdio cruxible-core -- uvx cruxible-core
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from cruxible-core <command>

### Codex

**Platform CLI**
```bash
codex mcp add cruxible-core --env CRUXIBLE_MODE=<CRUXIBLE_MODE> --env CRUXIBLE_ALLOWED_ROOTS=<CRUXIBLE_ALLOWED_ROOTS> -- uvx cruxible-core
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from cruxible-core <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "cruxible-core": {
            "command": "uvx",
            "args": [
                "cruxible-core"
            ],
            "env": {
                "CRUXIBLE_MODE": "<CRUXIBLE_MODE>",
                "CRUXIBLE_ALLOWED_ROOTS": "<CRUXIBLE_ALLOWED_ROOTS>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from cruxible-core <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "cruxible-core": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "cruxible-core"
            ],
            "env": {
                "CRUXIBLE_MODE": "<CRUXIBLE_MODE>",
                "CRUXIBLE_ALLOWED_ROOTS": "<CRUXIBLE_ALLOWED_ROOTS>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from cruxible-core <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e CRUXIBLE_MODE=<CRUXIBLE_MODE> -e CRUXIBLE_ALLOWED_ROOTS=<CRUXIBLE_ALLOWED_ROOTS> cruxible-core uvx cruxible-core
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from cruxible-core <command>

## When to use it
- Declare domain graph models and relationship policies in YAML
- Block direct database writes that require human or automated review
- Audit agent reasoning through deterministic receipt IDs
- Verify decision impact against scheduled outcome contracts

## Example prompts
- Run the `incident_impacted_suppliers` named query with `incident_id=INC-TW-RAIL-2026-07`
- Propose a new `incident_impacts_supplier` edge for review before applying it
- Check the recorded outcome receipt for the recent shipment hold decision

## Similar
- [State Memory MCP](https://affpapa.org/en/nevibecode/mcp/state-memory-mcp.md) — MCP server · ★ 39
- [async-io-model](https://affpapa.org/en/nevibecode/skills/async-io-model.md) — skill · 1300 installs
- [ship-checklist](https://affpapa.org/en/nevibecode/skills/ship-checklist.md) — skill · ★ 121
- [graph-viewer](https://affpapa.org/en/nevibecode/skills/graph-viewer.md) — skill · 1900 installs
- [antv-g6-graph](https://affpapa.org/en/nevibecode/skills/antv-g6-graph.md) — skill · 1100 installs
- [ae-analysis](https://affpapa.org/en/nevibecode/skills/ae-analysis.md) — skill · 869 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md