amu-pgvector

Reference implementation of Lineage-Aware Memory Governance (Sangaraju & Vissa, IEEE Access, 10.1109/ACCESS.2026.3730363) on PostgreSQL + pgvector.

The problem

Say Finance computes avg(income) for a customer segment and caches the result so the next agent that asks the same question doesn't have to recompute it. Later, a Marketing agent asks a semantically similar question -- "what's the average customer income by segment?" -- and a naive shared memory, gated only on the metric's name or content tags, serves back Finance's cached result. Marketing was never permitted to see income. The result itself doesn't look like income -- it's a number -- but it was derived from a column Marketing isn't permitted to touch, and nothing about matching on metric name or content catches that. That's the leak this project closes: gating reuse on how a result was derived, not on what it looks like.

60-second quickstart

git clone https://github.com/sangaraju1988/amu-pgvector.git
cd amu-pgvector
docker compose up -d
psql -h localhost -p 5433 -U amu_owner -d amu_dev -f sql/amu_pgvector.sql
# password: amu_owner_password

uv sync --all-packages --all-extras   # or: pip install amu-pgvector

from amu_pgvector import AMUStore
from amu_pgvector.embeddings import fake_embedder

DSN = "postgresql://amu_owner:amu_owner_password@localhost:5433/amu_dev"
embed = fake_embedder(dim=1536)  # swap for a real embedding model in production

admin = AMUStore(DSN)
admin.register_sensitive_column("income")
admin.grant_department_permission("Finance", "income")
admin.create_agent_role("finance_agent", "Finance", "finance_pw")
admin.create_agent_role("marketing_agent", "Marketing", "marketing_pw")

admin.record(
    "SELECT avg(income) FROM customers",
    {"avg": 82000},
    metric_name="avg_income",
    description="average customer income",
    owner_department="Finance",
    embed_fn=embed,
)

finance_dsn = "postgresql://finance_agent:finance_pw@localhost:5433/amu_dev"
marketing_dsn = "postgresql://marketing_agent:marketing_pw@localhost:5433/amu_dev"

AMUStore(finance_dsn).search("average customer income", k=5, embed_fn=embed)
# -> [SearchResult(metric_name='avg_income', ...)]

AMUStore(marketing_dsn).search("average customer income", k=5, embed_fn=embed)
# -> [] -- Marketing was never granted `income`, so Postgres itself
#          never returns the row, regardless of how the query is asked.

Every line above was run against this exact repo before being written here (see docs/design.md for what a from-scratch install actually looks like). amu_owner/amu_owner_password is the docker-compose default -- change it for anything beyond local development.

How the gate works

amu.memory_units is a normal Postgres table with FORCE ROW LEVEL SECURITY enabled. Every write goes through a trigger that extracts the lineage of the SQL that actually produced the cached result (via amu-governance's sql_lineage module -- not self-reported by the agent), closes it over any registered materialized-view/derived-table edges, and computes S(a): the set of sensitive columns that lineage actually touches. A SELECT policy enforces S(a) ⊆ P(d) -- the row is visible only if every column in S(a) is in the requesting role's permitted set P(d) -- for every query against the table, from every client: raw SQL, amu.search(), the Python client, the LangChain integration, and the MCP server all go through the same policy, because it's the table's policy, not any one client's filter.

sequenceDiagram
    participant Writer as amu_writer role<br/>(trusted interception layer)
    participant PG as Postgres: amu.memory_units<br/>(FORCE ROW LEVEL SE

... [View full README on GitHub](https://github.com/sangaraju1988/amu-pgvector#readme)