Hivemind: a runtime layer for multi-agent systems that refuses to be a framework

A layer under the framework, not a replacement for it

Hivemind describes itself as a Python-first runtime layer for multi-agent systems, with persistent run state, streaming execution events and a pluggable orchestration interface.

The first thing it does is say what it is not. It does not replace frameworks such as LangGraph, AutoGen or CrewAI. Instead it gives them a consistent execution model: agents are invoked as runs, runs produce ordered steps and messages, tool calls are recorded, and every state change can be streamed to a client.

That positioning is the whole design argument, and it is aimed at a specific moment. Agent frameworks are usually optimized for local composition, prompts, tools, graphs, roles and model calls. Production systems need runtime concerns that sit outside the framework itself, and the project lists them: durable run history across process restarts, ordered step, message and tool-call records for debugging and audit, streaming events for web clients and SDK consumers, cancellation, retry and resume primitives, a stable abstraction for switching or mixing orchestration frameworks, and an operator-facing console for inspecting active and historical runs.

The adapter mechanism is what makes the claim credible. The default adapter uses LangGraph, the official PydanticAI integration ships as an installable plugin, and additional adapters can be registered for AutoGen, CrewAI or an internal framework without changing the API or the database schema. The data model stays the same whichever engine is underneath, which is what makes the observability surface common rather than per framework.

The contributor-oriented stack is Java 21, Spring Boot 3, Python 3.12, SQLAlchemy 2, Alembic, Redis, `uv`, Next.js and TypeScript, and the project is custom-licensed open source with a `LICENSE` file, a Chinese README alongside the English one, and documentation for the architecture, the data model, the API contract and the deployment runbook.

Run, Step, Message, ToolCall and Checkpoint are database entities

The persistence model is the part of the project that does the heavy lifting, and it is deliberately conventional.

`Run`, `Step`, `Message`, `ToolCall` and `Checkpoint` are first-class database entities. They provide a common observability surface across different orchestration engines, which means the same query returns the same shape whether the run was driven by LangGraph, by the PydanticAI plugin or by something written in house.

The `Run` is the unit of work that an agent invocation becomes, and it has a lifecycle with named outcomes: `run.completed`, `run.failed`, `run.cancelled` and `run.waiting_human`. The last of those is the interesting one, because it is the point where an agent run stops and a person has to be involved, and the data model has a state for it rather than treating it as a failure.

`Step` and `Message` give the ordered record of what happened inside a run, and `ToolCall` records the calls made, which is the part an auditor actually wants. `Checkpoint` is what makes resume and retry possible across a process restart, and its presence as a first-class entity is the reason the project can claim durable run history rather than merely recent run history.

The implementation is SQLAlchemy 2 with Alembic, and the project layout makes the source of truth explicit: the `alembic/` directory is the database schema, described as the source of truth, while `models/` holds the ORM models and `schemas/` holds the Pydantic shapes that are shared. The Java side keeps its own DTOs, and the two languages are held together by the frozen `/v1` contract described in `docs/api-contract.md`.

SSE for live clients, signed webhooks for everything else

Two delivery mechanisms carry state changes out of the runtime, and they are aimed at different clients.

Server-Sent Events are the in-band channel. Run lifecycle changes are emitted as SSE events, so clients can follow execution without polling. The console uses exactly that: the Next.js console lists runs, opens run details, renders steps and messages, and subscribes to the live event stream.

Outbound webhooks are the out-of-band channel. Run outcomes are pushed to configured URLs with retries, and HMAC-signed when a secret is configured, for integrations that cannot hold an SSE stream. That last clause is the design rationale: a browser tab can hold a stream, a background job in another system cannot, and a webhook with retries and a signature is what a receiving system can verify and retry against.

The HMAC detail is the part that matters for anyone putting this in front of a third party. A webhook that is not signed is a webhook that anyone who learns the URL can forge, and the project treats the secret as optional configuration, which means the deployment has to decide.

The events are also bridged through the Java layer, since the diagram shows the console talking REST and SSE to the Spring Boot API, and the API talking jobs, cancel and events over Redis to the Python workers. So a client never talks to the worker directly, and the SSE stream is terminated at the API.

A Java API, a Python worker, Postgres and Redis

The architecture is unusual enough to be worth spelling out, because a Python-first project with a Java service in the middle needs a justification. The topology diagram in the README draws the path from the top down: the Next.js console talks REST to the Spring Boot API and receives SSE back from it, the API exchanges jobs, cancel signals and events with the Python worker over Redis, the worker drives the orchestrator adapter, and Postgres sits underneath holding the state.

The compose service for that worker shows the same wiring in configuration, with its dependencies declared as health conditions rather than as start order, so the worker does not begin before Postgres and Redis can answer:

  worker:
    build: ./backend
    container_name: agentflow-worker
    command: ["uv", "run", "python", "-m", "app.worker"]
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    environment:
      AGENTFLOW_DATABASE_URL: postgresql+asyncpg://agentflow:agentflow@postgres:5432/agentflow
      AGENTFLOW_REDIS_URL: redis://redis:6379/0
      AGENTFLOW_WORKER_MODE: queue

The HTTP layer that the frontend talks to is a Java and Spring Boot service in `backend-java/`. Agent orchestration runs in Python worker processes in `backend/` that consume a Redis-backed job queue and drive the adapters, LangGraph or Echo, to completion. Postgres holds the state, and the queue and the live event bus are Redis.

So the Python side owns the agent work and the Java side owns the API contract, the authentication and the client connections. The Java package path is `io.agentflow.api/`, with `controller/` for the `/v1` REST and SSE controllers and `dto/` for the data transfer objects.

The API supports tenant-scoped RBAC through API keys and OIDC Bearer tokens, with the identity provider setup, tenant claim requirements and group-to-role mapping documented separately in `docs/oidc.md`.

One thing to notice in the names: the containers, the environment variables and the Python package are all called agentflow, while the project and the repository are called Hivemind. The internal name has not been renamed to match the public one.

Quick start: Docker, uv, Maven and npm in four shells

The quick start is concrete and the requirements are listed up front: Docker, `uv`, Node.js 20 or later, JDK 21 and Maven 3.9 or later.

The first step brings up the infrastructure, Postgres and Redis, and the second applies the schema:

# Infrastructure
docker compose up -d postgres redis

# Database schema
cd backend && uv sync && uv run alembic upgrade head

Then three processes run in parallel, each in its own shell. The worker consumes the job queue:

# Worker (separate shell)
AGENTFLOW_WORKER_MODE=queue uv run python -m app.worker

The Java API serves the `/v1` endpoints:

# Java API (separate shell)
cd ../backend-java && mvn spring-boot:run

And the console is a Next.js dev server:

# Frontend (separate shell)
cd ../frontend && npm install && npm run dev

The console is then at `http://localhost:3000`, and the default `echo` adapter runs locally and does not require a model provider key, which means the whole stack can be brought up before any API key exists.

There is also a Compose route, which is the same schema command followed by the app profile:

cd backend && uv sync && uv run alembic upgrade head
docker compose --profile app up --build

The create-a-run sequence through the API is three calls. An agent is created with a name, an adapter and a config block:

curl -X POST http://localhost:8000/v1/agents \
  -H "content-type: application/json" \
  -d '{
        "name": "writer",
        "adapter": "langgraph",
        "config": {
          "model": "openai/gpt-4o-mini",
          "system_prompt": "You are a concise technical writer."
        }
      }'

A run is started against that agent, and the event stream is then subscribed to with `curl -N`, the no-buffer flag that makes the stream readable as it arrives rather than after it ends.

The Makefile is where the project actually meets CI

The `Makefile` at the root is the shortest description of how the project is worked on, because the target names are the day-to-day verbs.

up:
	docker compose up -d postgres redis

db-schema:
	cd backend && uv run alembic upgrade head

test:
	cd backend && uv run pytest -q

lint:
	cd backend && uv run ruff check .
	cd frontend && npm run lint

The `up` and `down` targets manage the infrastructure, `api`, `worker` and `frontend` run the three processes, `db-schema` applies the Alembic migration, `test` runs the backend unit tests, `lint` runs ruff and the frontend linter, and `format` runs ruff format.

Two targets are more interesting. `gen-openapi` exports `openapi/openapi.yaml` from the Spring Boot service with a script in `scripts/gen/`, and `gen-sdks` generates the REST stubs from that file. The SDKs in `sdk/python` and the TypeScript side are therefore generated artefacts, and `sdk-test` runs their test suites, Python and TypeScript, which is the check that the generated clients still match the contract.

The `integration` target is the end-to-end one. It brings up Postgres and Redis, syncs the backend with all extras, applies the schema, starts the app profile with `docker compose --profile app up -d --build`, then runs two scripts from `scripts/ci/`: `wait_for_http.py` against the health endpoint with a 240 second budget, and `java_stack_smoke.py` against the running API. The name of the first script says the real job, which is waiting for a stack that takes a while to become ready.

The Compose file also carries an observability profile. The worker is configured entirely through environment variables, `AGENTFLOW_DATABASE_URL` pointing at Postgres over asyncpg, `AGENTFLOW_REDIS_URL`, `AGENTFLOW_WORKER_MODE`, `AGENTFLOW_LOG_LEVEL`, and the OpenTelemetry variables `AGENTFLOW_OTEL_ENABLED`, `AGENTFLOW_OTEL_EXPORTER_ENDPOINT` and `AGENTFLOW_OTEL_SERVICE_NAME`. The profile adds an OpenTelemetry collector on the 4318 and 8889 ports and a Prometheus instance, and the collector configuration is mounted from `docker/otel-collector.yaml`.

Where Hivemind is the wrong tool

The limits are visible in the architecture, and they are the price of the abstraction.

The first is the JVM in the request path. A Python team that calls a model and returns a string now has a Spring Boot service, a Python worker, Postgres, Redis and a Next.js console between the idea and the answer. For a single agent invocation that finishes in one call, that is an unreasonable amount of machinery, and the project does not pretend otherwise, since it is explicitly aimed at teams moving from a prototype to an inspectable service.

The second is the schema commitment. The data model is not a view over a framework's internals, it is a set of first-class entities, and the API contract is described as frozen. A team that expects to change what a step is, or what a message is, will find the change expensive, and the generated SDKs mean the contract propagates further than the code.

The third is the adapter dependency. The value of the layer comes from the framework underneath it, so the framework still has to be chosen, and choosing one is a commitment the abstraction does not remove, only hides until the adapter has to be written.

The alternative is the one most teams start from: stay inside one orchestration framework, persist what that framework already gives you, and build the pieces you need, the event stream, the run history, the console, one at a time. The difference in approach is that Hivemind has already built those pieces and is asking for a Spring Boot service and a Postgres schema in exchange, while the alternative asks for a week of work per piece and no new runtime in the path. Which is cheaper depends entirely on how many agents and how many operators the team will have in a year.

The last detail to check before committing is administrative rather than technical. The repository has no GitHub releases, the last push was on 2026-10-15, and GitHub does not classify the repository under a standard licence, so the `LICENSE` file has to be read directly rather than assumed. The repository also carries a `deploy/` directory, and the deployment runbook in `docs/deployment.md` covers Compose, Helm and Terraform, which is the sign of a project that expects to be run in a cluster rather than on a laptop.

Editorial conclusion

Hivemind fits a team that has outgrown an agent prototype and needs run history that survives a restart, an event stream for clients, an audit trail of steps and tool calls, and the freedom to change orchestration framework without rewriting the persistence layer. It is the wrong tool for a single agent that finishes in one call, where the Spring Boot service, the worker, the schema and the console are a stack of infrastructure around a single request, and it is a poor match for a Python-only shop that does not want a JVM in the path. Before adopting it, read `docs/api-contract.md`, because the `/v1` contract is described as frozen and every SDK is generated from it, check that the orchestrator you use has an adapter or that you are willing to write one, and read the `LICENSE` file, since GitHub does not classify this repository under a standard licence.

Frequently asked questions

Official sources

1. Emiyaaaaa/HiveMind on GitHub
2. Issues
3. README