Struct GraphMemory 

pub struct GraphMemory { /* private fields */ }

High-level graph memory API - the main entry point for AINL memory.

Wraps a GraphStore implementation with a simplified 5-method API.

Implementations

impl GraphMemory

pub fn new(db_path: &Path) -> Result<Self, String>

Create a new graph memory at the given database path.

This will create the database file if it doesn’t exist, and ensure the AINL graph schema is initialized.

pub fn from_connection(conn: Connection) -> Result<Self, String>

Create from an existing SQLite connection (for integration with existing memory pools)

pub fn from_sqlite_store(store: SqliteGraphStore) -> Self

Wrap an already-open SqliteGraphStore (for hosts that manage connections externally).

pub fn write_episode( &self, tool_calls: Vec<String>, delegation_to: Option<String>, trace_event: Option<Value>, ) -> Result<Uuid, String>

Write an episode node (what happened during an agent turn).

Arguments

• tool_calls - List of tools executed during this turn
• delegation_to - Agent ID this turn delegated to (if any)
• trace_event - Optional orchestration trace event (serialized JSON)

Returns

The ID of the created episode node

pub fn write_fact( &self, fact: String, confidence: f32, source_turn_id: Uuid, ) -> Result<Uuid, String>

Write a semantic fact (learned information with confidence).

Arguments

• fact - The fact in natural language
• confidence - Confidence score (0.0-1.0)
• source_turn_id - Turn ID that generated this fact

Returns

The ID of the created semantic node

pub fn store_pattern( &self, pattern_name: String, compiled_graph: Vec<u8>, ) -> Result<Uuid, String>

Store a procedural pattern (compiled workflow).

Arguments

• pattern_name - Name/identifier for the pattern
• compiled_graph - Binary representation of the compiled graph

Returns

The ID of the created procedural node

pub fn write_procedural( &self, pattern_name: &str, tool_sequence: Vec<String>, confidence: f32, ) -> Result<Uuid, String>

Store a procedural pattern derived from a live tool sequence (heuristic extraction).

pub fn write_edge( &self, source: Uuid, target: Uuid, rel: &str, ) -> Result<(), String>

Write a graph edge between nodes (e.g. episode timeline follows).

pub fn recall_recent( &self, seconds_ago: i64, ) -> Result<Vec<AinlMemoryNode>, String>

Recall recent episodes (within the last N seconds).

Arguments

• seconds_ago - Only return episodes from the last N seconds

Returns

Vector of episode nodes, most recent first

pub fn recall_by_type( &self, kind: AinlNodeKind, seconds_ago: i64, ) -> Result<Vec<AinlMemoryNode>, String>

Recall nodes of a specific kind written in the last seconds_ago seconds.

pub fn write_persona( &self, trait_name: &str, strength: f32, learned_from: Vec<Uuid>, ) -> Result<Uuid, String>

Write a persona trait node.

pub fn store(&self) -> &dyn GraphStore

Get direct access to the underlying store for advanced queries

pub fn sqlite_store(&self) -> &SqliteGraphStore

SQLite backing store (for components such as ainl-graph-extractor that require concrete SQL access).

pub fn validate_graph( &self, agent_id: &str, ) -> Result<GraphValidationReport, String>

SqliteGraphStore::validate_graph for the same backing database (checkpoint / boot gate).

pub fn export_graph(&self, agent_id: &str) -> Result<AgentGraphSnapshot, String>

SqliteGraphStore::export_graph.

pub fn import_graph( &mut self, snapshot: &AgentGraphSnapshot, allow_dangling_edges: bool, ) -> Result<(), String>

SqliteGraphStore::import_graph — use allow_dangling_edges: false for normal loads; true only for repair.

pub fn agent_subgraph_edges( &self, agent_id: &str, ) -> Result<Vec<SnapshotEdge>, String>

SqliteGraphStore::agent_subgraph_edges.

pub fn write_node_with_edges( &mut self, node: &AinlMemoryNode, ) -> Result<(), String>

SqliteGraphStore::write_node_with_edges (transactional; fails if embedded edge targets are missing).

pub fn insert_graph_edge_checked( &self, from_id: Uuid, to_id: Uuid, label: &str, ) -> Result<(), String>

SqliteGraphStore::insert_graph_edge_checked.

pub fn read_runtime_state( &self, agent_id: &str, ) -> Result<Option<RuntimeStateNode>, String>

Read persisted RuntimeStateNode for agent_id (most recent row).

pub fn write_runtime_state( &self, state: &RuntimeStateNode, ) -> Result<(), String>

Upsert persisted RuntimeStateNode for the given agent (stable node id per agent_id).

pub fn write_node(&self, node: &AinlMemoryNode) -> Result<(), String>

Write a fully constructed node (additive API for callers that set extended metadata).