alibaba/UnifiedModel: a workspace-scoped object graph for AI agents

What UModel solves for teams wiring agents to enterprise data

The problem is not a missing database. It is that the same service is called a host in the CMDB, a pod in the orchestrator, and a row in the metrics backend, and an agent asked to investigate an incident has to reconcile those three names before it can read anything. UModel's answer is a model pack: a declaration of EntitySets, datasets, links, storage and relation semantics that becomes the shared vocabulary for a workspace. Runtime entities and topology relations are then written into an EntityStore that instantiates that model.

The audience is narrower than the README's framing suggests. It is for platform and observability engineers who already have telemetry and a service inventory and want one query surface over both, plus the agent developers who consume that surface through MCP. The README explicitly excludes cloud-hosted control planes, multi-tenant authorization and domain-specific read APIs outside Query Service from the open-source core, so this is a local runtime, not a managed product.

Model packs, EntityStore, and the three query surfaces

The repository layout matches the architecture section: cmd/ holds the server and CLI entry points, pkg/ and internal/ hold the runtime, api/ holds the OpenAPI contract and MCP tool schema, and schemas/ plus expanded_schemas/ hold the model definitions. A workspace is the isolation boundary, and the demo preloads one called demo.

The read path is deliberately small. Query Service answers three SPL surfaces: .umodel for the model itself, .entity for runtime entities, and .topo for topology. That is the whole query language surface described in the README, which is a constraint as much as a feature: an agent does not have to learn a general query language, but neither can it express arbitrary joins. AgentGateway and MCP sit on top of the same service, exposing discovery, resources, query examples and what the README calls safe tools. The dependency list is short, with go-ladybug as the graph store driver and cobra for the CLI, so the graph engine is a real component rather than an abstraction over an external service.

Installing UModel and running the demo workspace

The README lists Go 1.22 or newer, Make, Node.js 22 or newer for the Web UI, and pnpm 9 or newer as preferred, with corepack or npm exec as fallbacks handled by the Makefile. Confirm the toolchain before building anything:

make check-env

With the toolchain in place, one target starts the API and the Web UI and preloads the demo workspace. The README states that this uses GRAPHSTORE=memory and leaves no local demo data behind after the process stops.

make quickstart

Open http://localhost:5173, select demo, and the Explorer, Query, Data Store and Agent views are available. The API defaults to :8080 and the Web UI to 5173 according to the Makefile variables API_ADDR and WEB_PORT. For an agent, the README's first step is discovery through the CLI:

umctl agent discover demo

MCP clients connect through umodel-mcp. To shut everything down, the README gives one command:

make stop-all

The Makefile also exposes build-service for umodel-server, umctl and umodel-mcp, and a GRAPHSTORE variable whose default is file.memory, with local.ladybug available when the ladybug build tag is set.

Where UModel is the wrong choice

The memory graph store in the quickstart is the first limit. It is the right default for a demo because nothing persists, but an incident investigation that spans days cannot run on it, and the README does not describe a durability or backup story for the file-backed mode either. Plan for the storage question before you model anything.

The second limit is scope. The README is direct that cloud-hosted control planes, multi-tenant authorization and domain-specific read APIs outside Query Service are outside the public core. If your requirement is per-tenant isolation with hosted operations, this repository is not that product, and no amount of model authoring changes it.

The third is expressiveness. Three SPL surfaces cover model, entity and topology reads. Anything that looks like aggregation across arbitrary entity types has to be assembled by the client or expressed as a model-scoped query plan. Teams used to ad-hoc SQL over a warehouse will find the surface deliberately narrow.

Finally, the licence file does not carry a standard SPDX identifier. The README badge says Apache-2.0 while the repository metadata reports NOASSERTION, so read LICENSE and NOTICE before you depend on the terms.

How UModel differs from a CMDB or a standalone graph database

A traditional CMDB stores configuration items and their relationships, and its schema is usually owned by the CMDB team. UModel inverts that: the model pack is a file in your repository, versioned with your code, and the runtime is a local service you start. The difference shows up in who can change the vocabulary. With a CMDB you file a request; with UModel you edit a pack and reload.

A standalone graph database gives you a general query language and leaves the semantics to you. UModel trades that generality for a fixed read surface and an agent-facing contract: MCP resources, discovery and query examples are part of the repository, in api/mcp/tools.schema.json, not something you write yourself. If your team already has a graph database and a query layer the agents use happily, UModel adds a vocabulary layer you may not need. If the missing piece is exactly that vocabulary plus an MCP endpoint, the trade is worth examining.

Maintenance, releases, and licence cost

The repository is not archived and the last push was on 2026-09-02, so it is being worked on. Releases are frequent and small: v0.2.0 on 2026-06-10 introduced what the release notes call the plan/data mode contract and an agent-friendly query envelope, v0.3.0 followed on 2026-06-15, and v0.4.0 on 2026-06-16. Three releases in a week suggests a project still settling its interfaces, and the 0.x version numbers say the same thing. Expect the query envelope and MCP tool schema to move.

Upgrade cost is concentrated in three files: api/openapi/openapi.yaml, api/mcp/tools.schema.json and your model packs. If you generate SDKs from the OpenAPI contract, a minor release can change generated code. The Makefile has targets for this, including build-sdk-go and example-validate, and the repository ships example packs under examples/ that you can validate against. Budget for re-running those after each upgrade rather than assuming compatibility.

On licensing, the README badge states Apache-2.0 and the repository metadata reports NOASSERTION. Those disagree, and the LICENSE and NOTICE files at the repository root are the ones that govern. Have whoever handles licensing read them before you redistribute anything.

Editorial conclusion

Adopt UModel when you need a local, vendor-neutral vocabulary for entities, topology and telemetry that an agent can query through MCP, and when a memory graph store is enough for evaluation. Do not adopt it yet if you need a hosted control plane or multi-tenant authorization, both of which the README places outside the public core. Before committing, run make check-env and make quickstart, then read docs/en/architecture/runtime-flow.md to confirm the write and read paths match your topology.

Frequently asked questions

Official sources

1. alibaba/UnifiedModel on GitHub
2. Issues
3. Project website
4. README
5. Releases