pgContext: Instructions file for Codex

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)