primer-ai 0.5.0

A self-hosted, open-source platform for orchestrating fleets of small, context-optimized AI agents - built on one bet: a small, local open-weight model, given a clean and purpose-built context, can do genuinely useful work. Runs on hardware you already own.

Quickstart · What makes it different · Loop engineering · How it works · Docs · Contributing

Why Primer

A language model spreads a fixed budget of attention across every token in its context. Keep that context tight and the few tokens that matter get most of the attention; bloat it with stale history, unused tool definitions, and irrelevant background, and the signal thins out. Primer's bet is simple: give a small, local model exactly what it needs - and nothing more - and it can do genuinely useful work. Not replace a frontier model; just real work, on hardware you already own. It is a bet, not a benchmark, and it is still early - the best way to test it is to run it on your own workload and tell us where it falls apart.

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, agent graphs, knowledge collections, channels, triggers, and semantic search - self-hosted and integrated from the start.

What makes Primer different

A lot of what Primer ships - knowledge bases, channels, triggers, approvals - you will find in other agent frameworks too. These are the parts that were missing everywhere else, and they are what Primer is really about.

Batteries included

Everything else a real deployment needs, integrated from day one and self-hostable:

• Knowledge collections - ingest documents into vector collections; agents retrieve only the relevant chunks (semantic search / RAG).
• Channels - bridge agents to Slack, Telegram, and Discord: ask questions, request approvals, and kick off work from a message.
• Triggers - start a fresh session or graph run, or resume a parked one, on a cron schedule, a delay, or a webhook.
• Human approvals - gate sensitive tool calls behind a person's approval from a channel or the console before the agent proceeds.
• Web search - first-class web search built in.
• MCP-server toolsets - connect external MCP servers and expose their tools to your agents.
• Harnesses - package a tuned set of agents, graphs, and collections into a versioned, git-backed bundle you can share and deploy anywhere.

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.