AGENTS.md

AGENTS.md — installing & using pgContext with an AI agent

Instructions for an AI coding agent (or an automated environment) that needs to install pgContext, verify it, and wire it into an application. Everything here is non-interactive and copy-paste safe. For human-oriented docs see README.md and docs/.

What pgContext is (and why it's worth using)

pgContext is an Apache-2.0 PostgreSQL 17 and 18 extension (Rust + pgrx) that adds vector and hybrid retrieval inside PostgreSQL, beside the data it searches:

• One system of record. Your ordinary PostgreSQL tables stay authoritative. HNSW and other acceleration artifacts are derived and rebuildable — never a second, drifting copy of your data.
• Fast answers that are still correct. Exact search is the oracle: every approximate (HNSW) candidate is resolved back to the live row and scored exactly before it is returned.
• PostgreSQL's rules still hold. MVCC visibility, ACL/RLS, and SQL predicates apply to every result, so retrieval cannot surface a row the caller isn't allowed to see.
• Competitive performance. Page-native HNSW with SIMD distance kernels matches pgvector's recall and serves it several times faster on the recognized GloVe-100-angular benchmark. See docs/benchmarks/pgvector.md.

Wiring guidance for an application: treat the source PostgreSQL table as the truth, add embeddings as a vector column, create a pgcontext_hnsw index for approximate search, and order by the schema-qualified distance operator (ORDER BY embedding OPERATOR(pgcontext.<=>) $query) when you need exact ranking. Never persist the index as if it were primary data — it can always be rebuilt with REINDEX.

Environment facts (pins — do not guess)

Fact	Value
Extension name	pgcontext
Supported PostgreSQL majors	17 and 18
Docker images	ghcr.io/evokoa/pgcontext:pgMAJOR-v0.2.0 (multi-arch amd64/arm64; default aliases use PG17)
Rust (source build)	1.96.0
cargo-pgrx (source build)	0.19.1 (pin exactly)
License	Apache-2.0

Path A — Docker (preferred; zero build, most deterministic)

Use this unless the task specifically requires a source build. It needs only a working Docker daemon.

docker pull ghcr.io/evokoa/pgcontext:pg17-v0.2.0
docker run -d --rm \
  --name pgcontext \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=pgcontext \
  -p 5432:5432 \
  ghcr.io/evokoa/pgcontext:pg17-v0.2.0

# Wait for the server to accept connections (bounded, no infinite loop).
for i in $(seq 1 30); do
  docker exec pgcontext pg_isready -U postgres -d pgcontext && break
  sleep 1
done

Path B — build from source (when Docker is unavailable)

Requires PostgreSQL 17 or 18 with server development headers and a matching pg_config on PATH.

cargo install cargo-pgrx --version 0.19.1 --locked
cargo pgrx init --pg17="$(command -v pg_config)"
make install PG_CONFIG="$(command -v pg_config)"
psql -d postgres -c 'CREATE EXTENSION pgcontext;'

See docs/user_guide/installation.md for per-OS detail, uninstall, and troubleshooting.

Verify the install (smoke test — expect the asserted output)

Run this against the database where the extension is installed. For Path A prefix with docker exec pgcontext; for Path B run psql directly.

docker exec pgcontext psql -U postgres -d pgcontext -v ON_ERROR_STOP=1 <<'SQL'
CREATE EXTENSION IF NOT EXISTS pgcontext;

-- 1. Extension is registered.
SELECT extname, extversion FROM pg_extension WHERE extname = 'pgcontext';

-- 2. End-to-end: create a table, index it, run an ANN query.
CREATE TABLE IF NOT EXISTS agent_smoke (
    id        text PRIMARY KEY,
    embedding pgcontext.vector(3) NOT NULL
);
INSERT INTO agent_smoke VALUES
    ('a', '[1,0,0]'), ('b', '[0.9,0.1,0]'), ('c', '[0,1,0]')
ON CONFLICT (id) DO NOTHING;

CREATE INDEX IF NOT EXISTS agent_smoke_hnsw
    ON agent_smoke USING pgcontext_hnsw (embedding pgcontext.vector_hnsw_cosine_ops);

SELECT id
FROM agent_smoke
ORDER BY embedding OPERATOR(pgcontext.<=>) '[1,0,0]'::pgcontext.vector
LIMIT 1;
SQL

Success criteria:

• Step 1 returns one row: pgcontext | 0.2.0.
• Step 3 returns a (the nearest vector to [1,0,0]).

If step 1 returns no rows, the extension is not installed. If CREATE EXTENSION errors with a version mismatch, the extension binary and running PostgreSQL server were built for different majors.

Guardrails for automated changes

• Do not target PostgreSQL majors other than 17 or 18.
• Do not treat the HNSW index as primary data; it is a rebuildable artifact.
• Do not publish, push, tag, or upload release artifacts as part of an install task.
• Prefer CREATE EXTENSION IF NOT EXISTS and IF NOT EXISTS on smoke-test objects so re-runs are idempotent.

Where to look next

• SQL API: docs/user_guide/api_reference.md
• Indexes: docs/user_guide/indexes.md
• Filters & hybrid retrieval: docs/user_guide/filters.md
• Migrating from pgvector: docs/user_guide/pgvector_migration.md
• Known limitations: docs/known_issues.md