PactAI

A shared knowledge layer for coding agents.

Every session your agent starts, it starts from nothing. It rediscovers the project's conventions — usually by violating one and being corrected — and the correction is thrown away when the session ends. The next agent, on a different tool, repeats it.

PactAI holds a project's decisions, conventions and constraints, serves each agent only what governs the file in front of it over MCP, and records whether the code still honors them.

Agents read the code. PactAI keeps the verdict. It never sees the source.

The three invariants

Everything here follows from these. They are not preferences.

1. Atoms are a projection of documents. Knowledge is extracted from versioned prose, never hand-minted, so it can be re-derived when models improve and always carries a citable source.

2. Everything an agent writes is born provisional. Human ratification is what makes the knowledge base worth querying — it is the mechanism that produces trust, not friction to be optimized away.

3. Source code never leaves the machine. Reconciliation runs inside the customer's own agent session. What comes back is a verdict and a path:line.

Read docs/01-thesis.md for the argument and docs/02-principles.md for the design rules that follow from it.

Related MCP server: constraints-registry-mcp

Status

Phase 0. Monorepo skeleton, core schema with row-level security, CRUD, auth, CLI skeleton. There is no intelligence yet: extraction and embeddings do not begin before phase 1. Most documents under docs/ are placeholders that say so explicitly — do not infer a design from the existence of a file.

Stack

TypeScript on Node 26, pnpm and Turborepo. Hono with @hono/zod-openapi, where Zod schemas are the single source that generates the OpenAPI spec, the typed client and the CLI. Postgres 16 with pgvector (HNSW, 1024 dimensions), tsvector and pg_trgm. pg-boss for the queue, with transactional enqueue. Row-level security lands in the first migration, not later.

Getting started

nvm use              # Node 26, per .nvmrc
pnpm install         # also installs the git hooks
pnpm test            # green with no database — integration tests self-skip
pnpm lint
pnpm exec tsc -b

For anything touching the database:

docker run --rm -d -p 5432:5432 -e POSTGRES_PASSWORD=pact \
  --name pact-db pgvector/pgvector:pg16
cp .env.example .env
pnpm db:migrate

# The API refuses to start on a superuser or BYPASSRLS connection: such a role
# makes every tenant policy silently inactive while the application looks
# perfectly healthy. Create a restricted role once.
psql "$DIRECT_URL" -c "CREATE ROLE pact_api LOGIN PASSWORD 'pact_api' NOBYPASSRLS" \
                   -c "GRANT pact_app TO pact_api"

pnpm --filter @pactai/db run bootstrap "My org" "My name"
pnpm start                      # DATABASE_URL must be the pact_api role

Migrations and bootstrap run as the owner (DIRECT_URL); only the API uses the restricted role.

The last command creates an org, a human actor and an API key, printing the key once — only its SHA-256 is stored. It is ops tooling rather than an endpoint on purpose: an unauthenticated route that mints the first credential is an unauthenticated route that mints credentials.

pactai login --key pact_sk_… --url http://localhost:8080
pactai project create "My project"
pactai doc push docs/*.md --project <id>
pactai export ./my-knowledge     # full Markdown, yours to keep

Layout

infra/openapi/openapi.json is committed on purpose. CI regenerates it and fails on a diff, so a breaking API change shows up in review rather than at someone's integration.

License

Deliberately split, one repository, two halves:

• AGPL-3.0-only — api, core, db, worker. Running a modified PactAI as a network service obliges you to publish the modifications.

• Apache-2.0 — cli, mcp, sdk. These run on your own machine and are integration surface; integration surface with a copyleft obligation attached does not get integrated.

See NOTICE.