henosis

One asset context. Every decision.

Open-source context engine for physical assets.

Bring your operational systems together in one live, shared view so people, software and AI agents can find answers and take action without moving your data.

henos.io · Docs · Quickstart

Early and under active development. henosis is at an early stage and changing quickly — expect rough edges, and expect APIs, the ontology grammar and the CLI to change between releases. It is not yet recommended for production use.

Available today: the henosis Engine, REST API, MCP server and developer Explorer. The end-user Canvas shown above is in development and is not yet publicly available.

Built around how asset decisions are made

henosis organises information about your operation into five clear roles:

• Identity — what it is
• Location — where it is
• Observation — what it is doing, now and over time
• Documents — what is known about it
• Relationships — what it is connected to

These roles give each piece of information a clear purpose. Locations can appear on maps, observations can be plotted over time, and relationships can be followed directly. The meaning is built into the model instead of recreated in every tool.

A decision draws on those roles. An action can then write the result back to the source system, making the new state available to the next decision.

Engine, Explorer and Canvas

Engine

The Engine is the open-source software in this repository. It compiles the YAML model, resolves data from connected systems and serves the result through:

• REST API (/v1) for applications and integrations
• MCP tools (/mcp) for AI agents

Operational values stay in their source systems. The Engine stores the compiled model, routing information and relationship index.

Explorer

The Explorer is a developer interface included with the Engine. Use it to inspect the ontology, test connections, exercise REST endpoints and browse entities while building a model.

The Explorer is not an operational dashboard and is not the Canvas.

Canvas

The Canvas is a separate end-user workspace being developed on top of the Engine. It will bring maps, trends, entity details and agent-driven workflows into one operational surface.

The Canvas is not included in this repository and is not yet publicly available.

Why henosis

• One model, multiple interfaces. Applications use the REST API and AI agents call MCP tools today. The Canvas will bring the same model to people.
• MIT licensed and self-hosted. Run henosis in your own environment. Inspect, adapt and extend the code.
• Read data where it lives. henosis queries historians, maintenance records, maps and documents in their source systems. There is no migration or duplicate data layer.
• Write actions back to source systems. People and agents can act on what they find, with governed changes recorded where the work happens.

Works with what you already run

Connect the systems that already hold your operational context:

Need another source? Register a connector without forking or changing the Engine core. Snowflake support uses the optional snowflake dependency.

Where it fits

A generic graph can show what is connected without defining what each connection means. henosis gives information a clear role and provides tools for querying it, so applications and agents spend less time working out where to look.

henosis complements an existing data foundation. It does not replace a warehouse, knowledge graph, digital twin, dashboard or RAG system. It provides a live, opinionated asset model that those systems can supply or consume.

Install

henosis requires Python 3.11+. The package name is henosis-engine; the CLI command is henosis.

uv tool install henosis-engine

Or install from source:

git clone https://github.com/henos-io/henosis.git
cd henosis
uv tool install .

Quickstart

Create the included Cooper Basin example and start the local server:

henosis init cooper-basin
henosis serve -p cooper-basin --mcp

Open http://127.0.0.1:8000 to explore the live model. Search across entity types, then follow an asset's relationships, readings, location and documents.

The example is a synthetic upstream gas operation backed by local SQLite and Parquet sources. henosis init creates the project, generates its data, compiles the ontology and builds the relationship index.

Run henosis init --list to see the other worked examples. Each scaffolded project is yours to edit, and its YAML files are the source of truth for the model. See Ontology and data sources for the authoring guide.

Connect an AI agent

Start the server with MCP mounted, then point your client at it through mcp-remote:

henosis serve -p cooper-basin --mcp

{
  "mcpServers": {
    "henosis": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:8000/mcp", "--http"]
    }
  }
}

This works with any MCP client and lets several clients share one running server. Clients that speak Streamable HTTP natively can point at /mcp directly.

Alternatively, a client can launch henosis as a local subprocess over stdio, which needs no server running and no Node:

{
  "mcpServers": {
    "henosis": {
      "command": "henosis",
      "args": ["serve", "--stdio", "-p", "/absolute/path/to/cooper-basin"]
    }
  }
}

Use authentication and HTTPS for any deployment beyond localhost.

Status

henosis is an early technical preview. The Engine, compiler, ontology store, connectors, REST and MCP serving, CLI, developer Explorer and worked examples are built and exercised against the included scenarios.

APIs may change during the preview. The Canvas remains in development and is not yet available.

Feedback

If this idea maps to a problem in your environment, open an issue or contact Chris Bouras.

Security

The Engine does not yet include built-in authentication. serve binds to 127.0.0.1 by default. Any deployment reachable beyond localhost needs authentication and TLS in front of it.

To report a vulnerability, see SECURITY.md.

License

MIT License.