Skip to content
← Ecosystem

Vector memory with provenance

pg_phasevec v0.20.0 · preview 0.x

Readings with provenance: who read, what it read, and whether it still holds.

Vector search over a table has a quiet failure mode: the embedding was computed once, the row changed, and the index now answers from a memory of a row that no longer exists. pg_phasevec stores every reading with who took it, the hash of the exact text and when; an edited row becomes stale and is never returned as a confident wrong answer.

Install

CREATE EXTENSION pg_phasevec;

In plain words

A memory for the AI that remembers where every piece of data came from and warns when that data has changed.

  1. The situation

    Your assistant answers questions about contracts and prices using the company's documents.

  2. Without this piece

    A price changed a week ago. The AI keeps answering with the old one, with full confidence, because nobody told it the document changed.

  3. With this piece

    The memory knows that document changed after it was read: it marks it as stale and will not hand it out as a confident answer until it is read again.

Why it matters if you decide

  • Answers with a date and a source: you know which document and which version each one came from
  • Your data never leaves for an external service: the reading model is yours and the memory lives in your database
  • You can switch AI models without mixing old memories with new ones
For the technical team

The problem

A bare embedding does not know which row it came from

With pgvector alone, the vector is just another column: nothing records which model produced it or which text it read. Change the text, change the model, and the search keeps answering with the same confidence.

No cloud API and no network call: the reader is yours and local, and the codes live in your database next to the rows they describe.

How it works

Sealed reader, watch, reading

  1. 01

    A sealed reader

    reader_register(name, model_sha256, dims) identifies the reader by the sha256 of its weights (adapter and heads included) and the compute it runs on. Readings by different readers do not mix: they are foreign.

  2. 02

    A watch

    What must be findable: a source table, its key column, and one named recipe for the text to read (an expression over each row).

  3. 03

    A reading

    What the reader understood of a row: the hash of the text, its codes (a 64-bit sketch and a per-dimension code), and when. State pending, fresh, stale or foreign.

  4. 04

    Search in your own snapshot

    search() reads the question with the watch's reader; find() searches by codes; alike() returns rows like a given one. An edited row turns stale in the same transaction and find() withholds it, or returns a partial answer only when the caller asks for one.

SQL

A walk through it

Full surface: readers (register, seal, compute, switch), fill (watch, next, record, record_audit, record_failure), search (search, find, find_ivf, find_hybrid, alike), index (ivf_build, ivf_maintain, ivf_absorb), lexical and audit (coverage, truncations, dupes, audit_sample).

psql · pg_phasevecsql
CREATE EXTENSION pg_phasevec;
-- 1. Seal a reader by the sha256 of its weights and its dimensionality.
SELECT phasevec.reader_register('vec', '<model_sha256>', 1024);
-- 2. Watch the table: read r.body of each row, keyed by id.
SELECT phasevec.watch('docs', 'docs'::regclass, 'id', 'r.body', 'vec');
-- 3. Fill it: next() hands out the rows that still need reading, with the hash of their text.
SELECT phasevec.record('docs', key, 'vec', text_hash, code64, code)
  FROM phasevec.next('docs') AS r,
       LATERAL your_reader(r.body) AS codes(code64, code);
-- 4. Ask in words, in your own snapshot, never from stale text.
SELECT key, score, state, read_at
  FROM phasevec.search('docs', 'which fruit is red?', 10);

What it guarantees

What it guarantees, and what it trusts

  • Guaranteed: a reading names the reader and the exact text it was taken from. A row changed after it was read is reported as stale, not matched as if fresh.
  • Trusted: the reader is yours. pg_phasevec stores and searches the codes a sealed reader gives it and holds them to that reader's sha; it does not vouch for what the reader understood.
  • The maintenance surface (ivf_build, ivf_maintain, ivf_absorb, counts_compact) is REVOKEd from PUBLIC.
  • 0.16.0 is a security-hardening release: the SPI cursors that drive index build and maintenance skip rows with a NULL code instead of dereferencing it.
  • An optional claims layer: a role attaches a SQL proof to a row. A background worker re-checks each proof as its author, read-only, under a cost cap and a clock, and brief() serves only what still holds.
  • What shows claims (brief, recall, disputes, replacement, truth_coverage) shows a watch only to a role that may SELECT its table, and under row-level security only the rows that role sees.
  • A steward is a role the table's owner names with phasevec.steward() and that may settle claims: it counts while that owner owns the table and reaches only the rows row-level security lets it see.
  • It watches its own recall: recall_approve() records what a watch is served now as a baseline and recall_check() compares it later, with verdicts ok, degraded or critical. The settings are the stored ones: lowering nprobe or m in a session changes nothing.
  • pg_dump and pg_restore carry phasevec's data (since 0.19.0): readers, watches, readings, claims and the coarse index.

What it does not do

What it does not do

  • It ships no model: the reader (embeddings) is yours, sealed by its sha256.
  • It does not judge the quality of what the reader understood; it judges the provenance and freshness of every reading.
  • Readings by a different reader do not mix into a search: they are foreign by design.
  • It is a 0.x preview: its README lists open findings from the last red-team pass that 0.20.0 does not fix. One of them: with a concurrent delete and re-insert of a row by another tenant, a claim can be taken over on that tenant's new row. The full list is under "Known limits" in the README.
  • Restored into another cluster, authors and stewards are roles of the old cluster: every claim is an orphan until the table's owner adopts it, and stewards must be named again.
  • On PostgreSQL 18 there is no coarse-index copy shared across backends: each connection keeps its own, with the same answers.

For the enterprise

For the enterprise

This is the memory of a RAG system that can explain every answer: which model read which text and when, and that never answers confidently from a row that already changed. All inside PostgreSQL, without sending data to an external API.

  • Index audit: coverage, dupes, truncations, audit_sample
  • Controlled model change: sealed readers and reader_switch
  • Hybrid search (vector + lexical) in the same snapshot as your rows

This piece is not in the Enterprise 0.3.1 image, which ships pg_agent_gate, pg_living_assertions, pg_promise_guard and pg_grammar_guard. Install it separately from PGXN.

Spec sheet

Version
0.20.0, a 0.x preview (testing on PGXN; the stable release is still 0.18.0); the public image 0.3.6 ships 0.20.0 installed, not created (measured 2026-11-13)
PostgreSQL
18 or newer; no other extension required
License
Apache-2.0
Vulnerabilities
manuelreyesbravo@gmail.com, subject [pg_phasevec security]
Enterprise edition
Not in the Enterprise 0.3.1 image
Try it Talk