primer

An unopinionated, batteries-included agent-orchestration platform built around one bet: a small model given a clean, purpose-built context can rival a much larger one.

Quickstart · Features · How it works · Docs · Contributing

Why Primer

A language model spreads a fixed budget of attention across every token in its context at once. Keep the context tight and the few tokens that matter get most of that attention; bloat it with stale history, unused tool definitions, and irrelevant background and the signal thins out. Primer's core bet is that you often do not need the biggest model if you give the model you have exactly what it needs and nothing more - and that this is a lever on any model, large or small.

So instead of one giant agent with everything crammed into its prompt, Primer lets you orchestrate fleets of small, focused agents, each with a clean working context, wired together with the primitives a real deployment needs: LLM providers, workspaces, graphs, knowledge collections, channels, triggers, and semantic search - integrated from the start, runnable on your own hardware.

What you can build

Built for loop engineering

Loop engineering is the shift from prompting an agent turn-by-turn to designing the system that prompts it - a loop that wakes on a schedule, works toward a stated goal, checks its own output against evidence, and escalates to a human only when it should. The leverage moves from writing a good prompt to designing a good loop.

A loop needs a specific set of primitives. Primer ships all of them, integrated and self-hostable:

Primer does not press "go" on the loop for you - it gives you the orchestration substrate to build one and to keep a human in it where that matters. And the same context discipline that makes a single agent accurate is what lets a loop run for a long time without drifting: each iteration gets a clean, purpose-built context instead of an ever-growing transcript.

Quickstart

Pick whichever install fits. All three start the same server zero-config on an embedded SQLite database - perfect for a first look.

pipx (isolated CLI install; needs Python 3.12+):

pipx install 'primer-ai[full]'                   # batteries-included
primer api                                       # API + in-process worker

The bare pipx install primer-ai installs a lean core (REST API, console, MCP, SQLite/Postgres storage, and the API-based LLM/embedder providers). The [full] extra adds the optional backends - local HuggingFace embeddings, Docling ingestion, LanceDB, Slack/Telegram/Discord channels, and the container/Kubernetes workspace backends - which pull a larger ML stack. You can also pick à la carte: primer-ai[huggingface], [docling], [lance], [channels], [docker], [kubernetes].

Docker (no Python toolchain required):

docker run --rm -p 8000:8000 ghcr.io/primerhq/primer:latest

From source (for contributors):

git clone https://github.com/primerhq/primer.git
cd primer
uv sync --all-extras
uv run primer api

Then verify and open the console:

curl http://localhost:8000/v1/health             # -> {"status":"ok"}

The operator console is at http://localhost:8000/console/.

Going to Postgres (multi-process, semantic search, production)

Zero-config SQLite is single-process and ships without a vector store. For multiple workers, semantic search, or production, point Primer at Postgres:

docker compose up -d postgres                    # or: podman compose up -d postgres
cp config.example.yaml config.yaml               # set db.config.password to match
uv run primer api --config config.yaml

config.example.yaml documents every field. Environment variables override file values: every AppConfig field maps to PRIMER_<FIELD> (nested fields use __, e.g. PRIMER_DB__CONFIG__PASSWORD). The Docker image reads the same variables - set PRIMER_DB_HOST (and friends) and it renders a Postgres + pgvector config automatically; otherwise it runs the embedded-SQLite path above. For a SQLite database that survives container restarts, mount a volume at /app/data.

How it works

Primer is a stack of layers, where each layer keeps the one below it from getting cluttered:

• Context discipline - tool selection, meta-tools, and internal collections keep each agent's prompt lean.
• State - workspaces give agents a shared, minimal surface to hand off results without carrying history in-context.
• Sequencing - directed cyclic graphs express multi-step reasoning as structure instead of one giant prompt.
• Time - event-driven park-and-resume frees compute while work waits on a slow tool or a human.
• Sharing - harnesses package a working configuration into a versioned, git-backed bundle.
• Edges - channels, web search, and approval gates handle where agents reach outside the platform.

At runtime, requests arrive from many edges (REST/console, MCP clients, chat channels, triggers), become sessions / chats / graph runs that a worker pool claims and drives; each turn calls LLM providers, tools, workspaces, and collections, and can park on a human or event and resume later - all backed by Postgres.

Documentation

• Operator docs - served at /docs when the server is running.
• Agent-usage docs - docs/agents/ - how to drive a running Primer instance from an AI agent over MCP.
• Developer docs - docs/dev/ - architecture patterns and subsystem references. Start at docs/dev/README.md.

Contributing

Read AGENTS.md first - it is the authoritative contributor contract (project layout, the Definition of Done, how to run the suites, and the hard rules). CONTRIBUTING.md is the human-facing summary.

uv sync --all-extras
docker compose up -d postgres
# narrowed unit sweep (excludes e2e/distributed/ui_e2e):
uv run pytest tests/ -q --ignore=tests/distributed --ignore=tests/ui_e2e \
  --ignore=tests/e2e --ignore=tests/integration --ignore=tests/llm

See CODE_OF_CONDUCT.md for community expectations.

Security

Please report vulnerabilities privately - see SECURITY.md.

License

Primer is licensed under the Apache License 2.0. See LICENSE for the full text.