Struct PgGraphMemory 

pub struct PgGraphMemory<N, E> { /* private fields */ }

Postgres-backed GraphMemory<N, E>.

Cheap to clone — internal state is an Arc<PgPool> plus two owned table-name strings.

Implementations

impl<N, E> PgGraphMemory<N, E>

pub fn builder() -> PgGraphMemoryBuilder<N, E>

Start a fluent builder. connection_string is the only required field; everything else has a sensible default.

pub async fn list_nodes( &self, ns: &Namespace, limit: usize, offset: usize, ) -> Result<Vec<NodeId>>

Paginated node-id enumeration, ascending by id (UUID v7 mint-time order). Operator-side admin / migration path.

pub async fn list_node_records( &self, ns: &Namespace, limit: usize, offset: usize, ) -> Result<Vec<(NodeId, N)>>

where N: DeserializeOwned,

Paginated (NodeId, N) enumeration — single round-trip versus list_nodes + per-id node(). Operator-side bulk-export path.

pub async fn list_edges( &self, ns: &Namespace, limit: usize, offset: usize, ) -> Result<Vec<EdgeId>>

Paginated edge-id enumeration. Operator-side migration path.

pub async fn list_edge_records( &self, ns: &Namespace, limit: usize, offset: usize, ) -> Result<Vec<GraphHop<E>>>

where E: DeserializeOwned,

Paginated GraphHop<E> enumeration — full structural body in one round-trip. Operator-side bulk-export path.

pub async fn prune_orphan_nodes(&self, ns: &Namespace) -> Result<usize>

Drop every node with no incident edge — single SQL anti-join against the edges table. Two-phase prune companion to prune_older_than: the edge sweep leaves orphans that this call cleans up. Operator-side admin path.

Trait Implementations

impl<N, E> Clone for PgGraphMemory<N, E>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<N, E> Debug for PgGraphMemory<N, E>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<N, E> GraphMemory<N, E> for PgGraphMemory<N, E>

where N: Clone + Send + Sync + Serialize + DeserializeOwned + 'static, E: Clone + Send + Sync + Serialize + DeserializeOwned + 'static,

fn add_node<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _ctx: &'life1 ExecutionContext, ns: &'life2 Namespace, node: N, ) -> Pin<Box<dyn Future<Output = Result<NodeId>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Insert node and return its assigned id.

fn add_edge<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, _ctx: &'life1 ExecutionContext, ns: &'life2 Namespace, from: &'life3 NodeId, to: &'life4 NodeId, edge: E, timestamp: DateTime<Utc>, ) -> Pin<Box<dyn Future<Output = Result<EdgeId>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait,

Insert an edge from from to to carrying edge. timestamp is supplied by the caller so re-inserting after a replay produces deterministic edges.

fn add_edges_batch<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _ctx: &'life1 ExecutionContext, ns: &'life2 Namespace, edges: Vec<(NodeId, NodeId, E, DateTime<Utc>)>, ) -> Pin<Box<dyn Future<Output = Result<Vec<EdgeId>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Insert a batch of edges atomically. Each tuple is (from, to, edge, timestamp); endpoints must already exist (same contract as Self::add_edge). Returns the assigned EdgeIds in input order.

fn get_node<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _ctx: &'life1 ExecutionContext, ns: &'life2 Namespace, id: &'life3 NodeId, ) -> Pin<Box<dyn Future<Output = Result<Option<N>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Look up a node by id (verb-family get per .claude/rules/naming.md — single-item primary-key lookup).

fn get_edge<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _ctx: &'life1 ExecutionContext, ns: &'life2 Namespace, edge_id: &'life3 EdgeId, ) -> Pin<Box<dyn Future<Output = Result<Option<GraphHop<E>>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Look up an edge by id and return the full structural body (GraphHop<E> — from, to, edge, timestamp). Operators rarely want the payload alone for edges; the endpoints and timestamp are usually load-bearing for any follow-up decision (audit context, freshness check, neighbour navigation). Returning the full hop saves a second lookup.

fn neighbors<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _ctx: &'life1 ExecutionContext, ns: &'life2 Namespace, node: &'life3 NodeId, direction: Direction, ) -> Pin<Box<dyn Future<Output = Result<Vec<(EdgeId, NodeId, E)>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Edges incident to node in the requested direction. Each triple is (EdgeId, neighbour NodeId, edge payload).

fn traverse<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _ctx: &'life1 ExecutionContext, ns: &'life2 Namespace, start: &'life3 NodeId, direction: Direction, max_depth: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<GraphHop<E>>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Breadth-first traversal starting at start, expanding up to max_depth hops along edges in the requested direction. Returns the visited hops in BFS order (excluding the seed node, which has no inbound edge in this traversal). Use Direction::Both for relationship-graph queries that don’t care about edge polarity (knowledge graphs typically want this).

fn find_path<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, _ctx: &'life1 ExecutionContext, ns: &'life2 Namespace, from: &'life3 NodeId, to: &'life4 NodeId, direction: Direction, max_depth: usize, ) -> Pin<Box<dyn Future<Output = Result<Option<Vec<GraphHop<E>>>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait,

Shortest unweighted path from from to to (BFS) along edges in the requested direction. Returns the sequence of hops; Some(vec![]) means from == to (already at destination — no edges traversed); None means no path exists within max_depth hops.

fn temporal_filter<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _ctx: &'life1 ExecutionContext, ns: &'life2 Namespace, from: DateTime<Utc>, to: DateTime<Utc>, ) -> Pin<Box<dyn Future<Output = Result<Vec<GraphHop<E>>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Edges whose timestamp falls in [from, to). Useful for audit-log style queries (“what relationships did the agent learn last week”).

fn node_count<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _ctx: &'life1 ExecutionContext, ns: &'life2 Namespace, ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Count nodes in ns. Cheap operator metric for size-based decisions (paginate vs stream, fast-fail empty-namespace check, audit / dashboard surface). Default impl returns 0.

fn edge_count<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _ctx: &'life1 ExecutionContext, ns: &'life2 Namespace, ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Count edges in ns. Cheap operator metric — same rationale as Self::node_count. Default impl returns 0.

fn delete_edge<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _ctx: &'life1 ExecutionContext, ns: &'life2 Namespace, edge_id: &'life3 EdgeId, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Drop one edge by id. Idempotent — deleting an absent edge succeeds. Required — backends that don’t support edge deletion are degenerate; closed the CRUD-completeness gap.

fn delete_node<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _ctx: &'life1 ExecutionContext, ns: &'life2 Namespace, node_id: &'life3 NodeId, ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Drop one node by id and every edge incident to it. Cascades — operators that don’t want cascading delete every incident edge first via Self::delete_edge and then call this. Returns the count of removed edges so callers can log or expose cleanup metrics; 0 when the node had no edges (or was absent — the operation is idempotent).

fn prune_older_than<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _ctx: &'life1 ExecutionContext, ns: &'life2 Namespace, ttl: Duration, ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Drop every edge in ns whose timestamp is older than ttl ago. Returns the count of removed edges so callers can log or expose pruning metrics.