Skip to content
ContextUnity

Quick Start

What this covers

This guide is for the open-source services that ship as separate Git repositories under the ContextUnity organization:

ComponentGitHub repositoryInstallable package name (PyPI)
ContextUnity CoreContextUnity/contextunity-corecontextunity-core (coming to PyPI)
ContextBrainContextUnity/contextbraincontextunity-brain (coming to PyPI)
ContextRouterContextUnity/contextroutercontextunity-router (coming to PyPI)
ContextWorkerContextUnity/contextworkercontextunity-worker (coming to PyPI)

Today: clone the repositories and install with uv, wiring Core into the other three via a local path source (below). PyPI-only installs for the same package names are planned; when they land, you will be able to uv add contextunity-core (and peers) without cloning Core first.

Prerequisites

  • Python 3.13+
  • uv
  • PostgreSQL 16+ with vector and ltree extensions (Brain)
  • Redis (Router — typical local setup)
  • Temporal in dev mode (Worker — temporal server start-dev, or your own cluster)

1. Clone the four repositories

Use a sibling directory layout so each service can reference Core with a short relative path:

Terminal window
mkdir contextunity && cd contextunity


git clone https://github.com/ContextUnity/contextunity-core.git
git clone https://github.com/ContextUnity/contextbrain.git
git clone https://github.com/ContextUnity/contextrouter.git
git clone https://github.com/ContextUnity/contextworker.git

2. ContextUnity Core (kernel)

Repository: github.com/ContextUnity/contextunity-core

Terminal window
cd contextunity-core
uv sync
uv run pytest
  • CLI: contextunity-core (see --help after install).
  • Imports: contextunity.core (types, gRPC stubs, RouterClient / BrainClient, tokens).

3. Point Brain, Router, and Worker at your Core clone

Until contextunity-core is consumed from PyPI alone, add a path source in each service repository’s pyproject.toml (paths assume the sibling layout from step 1):

[tool.uv.sources]
contextunity-core = { path = "../contextunity-core" }

Adjust ../contextunity-core if your directories differ. Then run uv sync in each service checkout so the resolver picks up the local kernel.

4. ContextBrain

Repository: github.com/ContextUnity/contextbrain

Terminal window
cd ../contextbrain
uv sync


createdb brain
psql brain -c "CREATE EXTENSION IF NOT EXISTS vector;"
psql brain -c "CREATE EXTENSION IF NOT EXISTS ltree;"
uv run alembic upgrade head


export BRAIN_DATABASE_URL="postgresql://USER:PASS@localhost:5432/brain"
export EMBEDDER_TYPE="openai"
export OPENAI_API_KEY="sk-..."   # when using OpenAI embeddings


uv run python -m contextunity.brain
# equivalent: uv run contextbrain

Defaults and full tables of environment variables are in the ContextBrain repository README.md.

5. ContextRouter

Repository: github.com/ContextUnity/contextrouter

Terminal window
cd ../contextrouter
uv sync


export REDIS_URL="redis://localhost:6379/0"
export CU_BRAIN_GRPC_URL="localhost:50051"
export CU_ROUTER_DEFAULT_LLM="openai/gpt-5-mini"
export OPENAI_API_KEY="sk-..."


uv run python -m contextunity.router
# equivalent: uv run contextrouter

Clients (and Core’s defaults) typically use CU_ROUTER_GRPC_URL (for example localhost:50050) to reach the Router gRPC endpoint. Match that to the address and port your Router process listens on; see the ContextRouter README.md and Router configuration.

6. ContextWorker (optional)

Repository: github.com/ContextUnity/contextworker

Terminal window
cd ../contextworker
uv sync


export TEMPORAL_HOST="localhost:7233"


uv run python -m contextunity.worker
# Temporal worker loop, if you use the CLI flags from the Worker README:
# uv run python -m contextunity.worker --temporal

Use contextworker for Typer-based CLI entrypoints where documented in the Worker repository.

7. Next steps

To call Router from Python after it is running, configure CU_ROUTER_GRPC_URL and use RouterClient / SyncRouterClient from contextunity.core as described in Core SDK.