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 upsert_anchored_summary( &self, agent_id: &str, summary_payload: &str, ) -> Result<Uuid, String>

Upsert a serialized anchored summary for agent_id.

summary_payload should be a JSON-serialized AnchoredSummary from the ainl-context-compiler crate. Returns the stable node id (same value for repeated calls with the same agent_id).

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

Fetch the most recent anchored-summary payload for agent_id, if any.

Returns the raw JSON string (caller deserializes into AnchoredSummary).

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).

This path treats the row as curated (prompt-eligible) so a single write is visible in suggested-procedure style recall; use Self::write_node with a hand-built node if you need candidate-only semantics.

pub fn write_procedure_artifact( &self, artifact: &ProcedureArtifact, ) -> Result<Uuid, String>

Store a portable procedure artifact as a procedural graph node.

The canonical JSON artifact is stored in compiled_graph so older graph consumers can ignore it safely, while new consumers can recall and deserialize validated procedure artifacts without adding a separate table.

pub fn write_procedure_artifact_for_agent( &self, agent_id: &str, artifact: &ProcedureArtifact, ) -> Result<Uuid, String>

Store a portable procedure artifact for a specific agent.

pub fn upsert_procedure_artifact_for_agent( &self, agent_id: &str, artifact: &ProcedureArtifact, ) -> Result<Uuid, String>

Update an existing procedural node for artifact.id, or write a new one if no node exists.

pub fn recall_procedure_artifacts( &self, ) -> Result<Vec<ProcedureArtifact>, String>

Recall portable procedure artifacts previously stored with Self::write_procedure_artifact.

pub fn search_procedure_artifacts_for_agent( &self, agent_id: &str, intent: &str, available_tools: &[String], limit: usize, ) -> Result<Vec<ProcedureArtifact>, String>

Search validated/promoted procedure artifacts by intent text and required tool overlap.

pub fn record_procedure_reuse_outcome_for_agent( &self, agent_id: &str, outcome: &ProcedureReuseOutcome, ) -> Result<Uuid, String>

Update artifact lifecycle and fitness after an attempted reuse.

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 find_procedural_by_tool_sequence( &self, agent_id: &str, tool_sequence: &[String], ) -> Result<Option<AinlMemoryNode>, String>

Find a recent procedural (tool-sequence) row for this agent whose tool_sequence matches tool_sequence (per-element trim). Returns the newest match if several exist (e.g. legacy duplicates before merge).

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).

pub fn insert_trajectory_detail( &self, row: &TrajectoryDetailRecord, ) -> Result<(), String>

Insert a detailed trajectory row (see SqliteGraphStore::insert_trajectory_detail).

pub fn list_trajectories_for_agent( &self, agent_id: &str, limit: usize, since_timestamp: Option<i64>, ) -> Result<Vec<TrajectoryDetailRecord>, String>

Recent trajectory detail rows for an agent (see SqliteGraphStore::list_trajectories_for_agent).

pub fn count_trajectory_details_before( &self, agent_id: &str, before_recorded_at: i64, ) -> Result<usize, String>

How many ainl_trajectories detail rows would be removed by Self::prune_trajectory_details_before (same before_recorded_at semantics).

pub fn prune_trajectory_details_before( &self, agent_id: &str, before_recorded_at: i64, ) -> Result<usize, String>

Remove persisted trajectory detail rows with recorded_at strictly before before_recorded_at (seconds).

This targets the ainl_trajectories table only. Graph Trajectory nodes and cross-links are not deleted here; use exports / graph tooling if you need a full-store consistency pass after pruning.

pub fn search_failures_for_agent( &self, agent_id: &str, query: &str, limit: usize, ) -> Result<Vec<AinlMemoryNode>, String>

Search persisted FailureNode rows for an agent (FTS5 over ainl_failures_fts).

pub fn search_all_nodes_fts( &self, agent_id: &str, query: &str, project_id: Option<&str>, limit: usize, ) -> Result<Vec<AinlMemoryNode>, String>

Full-graph FTS5 search (ainl_nodes_fts); see SqliteGraphStore::search_all_nodes_fts_for_agent.