PG_DGRAPH: The Agent That Knows What It Doesn't Know

We gave agents perfect documents. We forgot to give them a mirror.

Where PG_FACETS Left Off

A few months ago, we introduced PG_FACETS — a PostgreSQL-native faceted search engine built specifically for RAG pipelines and AI agents. The promise was clear: give agents the right documents in milliseconds, at scale, without the overhead of a separate search infrastructure. Hybrid retrieval, Roaring Bitmaps, BM25 plus embeddings, multi-dimensional filtering — all colocated inside the same PostgreSQL instance your data already lives in.

It worked. Agents got better context. Hallucinations from poor retrieval dropped. Latency improved.

But solving retrieval exposed the next problem. And this one is harder.

An agent that retrieves the right document about Belgian contract law still doesn't know whether it is equipped to reason about it. It can surface a clause about force majeure. It cannot tell you whether it understands the dependency chain that clause implies — jurisdiction, precedent, the specific regulatory body, the enforcement history. It retrieves with confidence. It reasons with unknown blind spots.

PG_FACETS solved "which documents?"

PG_DGRAPH solves "am I equipped to understand what I just found?"

The Metacognition Problem

There is a well-established distinction in epistemology between knowing something and knowing that you know it.

Metacognition — the capacity to reason about one's own reasoning — is trivial for humans in professional contexts. A junior lawyer knows to escalate a case to a senior partner when she reaches the boundary of her expertise. She doesn't guess. She recognizes the edge.

Current AI agents don't have this. They have confidence levels on individual tokens, but no structural model of their own knowledge topology. They don't know what they don't know. Worse, they often don't know that they don't know it.

In low-stakes contexts, this is a nuisance. In compliance, legal, medical, or financial contexts, it is a liability. An agent that is wrong with confidence is more dangerous than one that is wrong and knows it.

The root cause is architectural. Today's agents have no persistent, traversable representation of their own knowledge structure — what concepts they cover, what dependencies connect them, where the gaps are, and what those gaps mean for a specific task.

That is not a prompt engineering problem. It is a data structure problem.

Why Graphs — The Technical Foundation

Tables, Documents, Graphs: A Progression

To understand why PG_DGRAPH uses directed graphs, it helps to be explicit about what each data structure can and cannot represent.

A table represents isolated facts. Rows, columns, values. Highly queryable, but flat. You can know that "regulation X exists" and "competency Y exists." You cannot represent that one requires the other, or that the relationship flows in one direction only.

A document represents rich content. Embeddings let you find documents that are semantically close to a query. But semantic proximity is not topological structure. Finding a document about GDPR does not tell you how GDPR's concepts depend on each other, or which competencies an agent needs to navigate them correctly.

A directed graph represents relationships as first-class citizens. Nodes are entities. Edges connect them. And crucially — edges have direction.

Directed Graphs: Asymmetry as Information

This is the key technical insight: in a directed graph, A → B is not the same as B → A.

"Regulation X requires competency Y" is a directional statement. If you flip it — "competency Y requires regulation X" — you get a different and likely false claim. A non-directed graph loses this information. A table cannot represent it cleanly at all.

This matters enormously for knowledge modeling. Professional domains are full of asymmetric dependencies:

• A legal procedure requires understanding a specific statute. The reverse is not true.
• A diagnostic protocol requires prior triage knowledge. Not the other way around.
• An onboarding workflow requires completion of a compliance certification. The certification does not require the workflow.

When you model an agent's knowledge as a directed graph, you can ask traversal questions that are impossible otherwise:

• "To handle this compliance task, which knowledge nodes does the agent need to traverse?"
• "Which of those nodes are missing from this agent's graph?"
• "What is the shortest acquisition path to fill those gaps before deployment?"

PG_DGRAPH — Architecture

PG_DGRAPH is a PostgreSQL extension that implements directed graph storage and traversal natively, colocated with your relational and PG_FACETS data.

Nodes represent entities: concepts, competencies, roles, agents, documents, regulations, workflow steps.

Directed edges represent relationships between nodes, with properties (weight, confidence, type, timestamps) stored inline.

Traversal algorithms run inside PostgreSQL: Breadth-First Search, Depth-First Search, shortest path computation, cycle detection, reachability queries. No external graph engine. No network hop. The same ACID transaction that writes your business data can write a new knowledge edge.

Integration with PG_FACETS is where the architecture becomes significantly more powerful. A single query can simultaneously traverse the agent's knowledge graph and filter documents by facets:

sql-- Find documents about "GDPR data transfer"
-- but only return them if the agent has the required knowledge nodes
SELECT d.*
FROM pg_facets_search('GDPR data transfer') d
JOIN dgraph_reachable('agent:compliance-v2', 'competency:data-transfer') r
ON r.reachable = true
WHERE d.regulation_type = 'GDPR';

This is not two systems talking to each other. It is one system with two complementary engines sharing the same transaction log, the same indexes, the same operational overhead.

The Agent Self-Model

PG_DGRAPH enables something that does not exist in current agent architectures: a persistent, updatable, queryable model of what an agent knows, what it can do, where its gaps are, and what it needs to learn.

Four dimensions, mutually exclusive and collectively exhaustive:

Knowledge Topology — What It Knows

Factual knowledge nodes (concepts, facts, entities), procedural knowledge nodes (how to perform a task), and contextual knowledge nodes (when and why a procedure applies) are stored as graph nodes with directed dependency edges between them. The graph makes explicit which concepts require prior understanding of others.

Capability Graph — What It Can Do

Tool nodes represent available integrations. Action nodes represent permitted operations. Workflow nodes represent end-to-end processes the agent is authorized to execute. Edges from knowledge nodes to capability nodes represent the cognitive prerequisites for using a tool correctly — not just having API access to it.

Gap Graph — What It Doesn't Know

When the agent's graph is compared against a domain ontology (a reference graph representing the full knowledge structure of a professional field), missing edges and absent nodes become explicit. These are known unknowns — structured gaps, not vague uncertainty.

Learning Graph — What It Must Acquire

Given a target task or domain, the learning graph is the shortest path from the agent's current knowledge topology to the coverage required. Not "study everything about compliance," but "to handle this specific workflow, the agent needs nodes X, Y, and Z, in that dependency order."

The Hard Problem: Unknown Unknowns

The four-quadrant model above handles known gaps. But the most dangerous gaps are the ones neither the agent nor its operators are aware of.

PG_DGRAPH addresses this through ontology-driven gap inference. When a domain ontology specifies that a certain edge should exist between two concepts — because any competent practitioner in that field would understand the connection — and that edge is absent from the agent's graph, the system can flag it as an inferred gap, even if no explicit query revealed it.

This does not fully solve the unknown unknowns problem — it cannot, by definition. But it shifts the boundary. It transforms some unknowns into knowns before a task is attempted, not after it fails.

Professional Domain Graphs

The second major capability of PG_DGRAPH is modeling professions as graphs — and using that model to reason precisely about what an agent can cover, where human oversight remains necessary, and how to design the handoff.

A Profession as a Graph

Every professional role can be decomposed into:

• Competency nodes: discrete units of knowledge or skill required for the role
• Task nodes: concrete activities performed in the role
• Decision nodes: judgment calls that require specific competency combinations
• Regulation nodes: external constraints the role must navigate

The edges between them define the dependency structure: which competencies are prerequisites for which tasks, which tasks trigger which decisions, which decisions are governed by which regulations.

A compliance officer's graph looks different from a junior lawyer's graph. Both look different from a customer support L2 engineer's graph. These are not the same profession with different labels. They are structurally distinct topologies.

Substitutability — Making the Debate Measurable

The question "can an AI agent replace this role?" is currently debated at the level of vibes and anecdotes. PG_DGRAPH makes it a graph query.

Coverage score: the percentage of a role's competency graph that the agent can traverse without hitting a gap node. 100% coverage means the agent can, in principle, execute the full role. 60% coverage means 40% of the role requires human involvement or escalade.

Gap nodes: the specific competency nodes where the agent's knowledge is absent or insufficient. These become the precise boundaries of a human-in-the-loop policy — not a general disclaimer, but a structured rule: "when task execution requires traversal through node X, escalate."

This reframes the augmentation vs. replacement debate as a measurable spectrum, not a binary choice.

The coverage percentages above are not fixed. They depend on the agent's specific training, the organization's ontology, and the regulatory context. PG_DGRAPH makes them computable rather than assumed.

Challenging the Premise

Four objections come up consistently. They deserve direct answers.

"We already have Neo4j / Memgraph / ArangoDB for graph work."

Separate graph databases introduce a transactional boundary. Every write to your relational store that should update the knowledge graph requires a synchronized write to a second system. Consistency is your problem. Latency increases. Schema drift accumulates. Operational complexity doubles. PG_DGRAPH inside PostgreSQL means one transaction, one schema, one operational surface. The agent's knowledge graph is updated in the same commit that updates the underlying data.

"Tool-calling already handles what agents don't know — they just call a tool."

Tool-calling is procedural. Knowing you have access to an API is not the same as understanding the domain that API operates in. An agent can call a legal database API without understanding the dependency between the articles it retrieves. It can call a medical records API without understanding clinical protocols. Access is not comprehension. PG_DGRAPH models the comprehension layer, not the access layer.

"Knowledge graphs go stale. The maintenance cost is prohibitive."

Static knowledge graphs built by human ontologists do go stale. PG_DGRAPH is designed for dynamic graphs: edges are added, weighted, and revised by agents themselves as they operate. The graph is not a monument — it is a living data structure updated transactionally. Agents are actors in the graph, not just consumers of it.

"LLMs already have world knowledge baked in. Why add a layer?"

LLMs have broad, general knowledge. They do not have your organization's ontology, this regulatory jurisdiction's specific dependency structure, this agent's authorized scope, or this workflow's required competency path. The gap between general world knowledge and task-specific domain topology is precisely where errors happen. PG_DGRAPH fills that gap with structure, not prompting.

Use Cases

Agent Certification Before Deployment

Before an agent goes live in a regulated environment, run a coverage query against the domain ontology for its target role. Identify every gap node. Define escalation rules for each one. This is not a best-effort review — it is a structured audit with a queryable output. Compliance teams can sign off on an agent the same way they sign off on a human employee's certification.

Multi-Agent Routing by Competency

In a multi-agent system, PG_DGRAPH becomes a competency router. When a task arrives, the system queries which agent in the pool has the highest coverage score for the required knowledge path. Tasks are routed not by agent name or category, but by traversable competency fit. The right agent for the job is a graph query result.

Structured Learning Path Generation

When an agent needs to expand its coverage for a new domain, PG_DGRAPH computes the minimal acquisition path: the ordered sequence of knowledge nodes the agent must integrate, respecting dependency order, to reach the required coverage threshold. "Study compliance" becomes "integrate nodes A, then B and C in parallel, then D — because D depends on B and C."

Precise Human-in-the-Loop Triggers

Current human escalation policies are blunt: confidence below threshold X, escalate. PG_DGRAPH enables structural triggers: when task execution requires traversal through a node marked as a gap, escalate — and tell the human operator exactly which gap triggered the escalation and why it exists. Not "I'm not sure," but "this task requires competency node regulatory:art-49-GDPR which is absent from my graph. Here is what I know up to that point."

The Stack: PG_FACETS + PG_DGRAPH Together

The two extensions are designed as complementary layers, not competing products.

textIncoming Agent Task
│
▼
[PG_DGRAPH]
"Am I equipped for this task?"
"What path does this task require?"
"Where are my gaps?"
│
├── Gap detected → escalate with structured reason
│
▼ (equipped or partial coverage confirmed)
[PG_FACETS]
"Which documents are relevant to this task?"
"Filter by domain, recency, authority, format"
│
▼
LLM Context Window
Documents + knowledge metadata + gap flags
│
▼
Response / Action / Structured Escalation

PG_FACETS optimizes the context fed to the model. PG_DGRAPH validates whether the model is structurally ready to process that context correctly.

Together, they form a complete epistemic stack: the right information, routed to the right agent, with honest accounting of what that agent can and cannot reason about.

What This Changes

The current generation of AI agents is defined by what they can retrieve and generate. The next generation will be defined by what they know about themselves.

An agent that understands its own knowledge topology — its coverage, its gaps, its dependencies, its learning path — is an agent you can actually deploy in consequential environments. Not because it is infallible, but because its failure modes are explicit, bounded, and manageable.

PG_DGRAPH is not a silver bullet for AI reliability. It is a structural foundation for building agents that are honest about what they don't know, precise about where they need help, and capable of growing their competency in a way that is traceable and auditable.

The question is no longer whether your agents are intelligent enough. The question is whether they know themselves well enough to be trusted.

PG_DGRAPH is in active development as part of the MindFlight Open Source stack. If you are working on enterprise AI deployments, multi-agent orchestration, or regulated domain automation and want early access, reach out.