Struct GraphMemory 

pub struct GraphMemory { /* private fields */ }

The main entry point for graph memory operations.

Implementations

impl GraphMemory

pub async fn open(path: &Path) -> Result<Self, GraphError>

Open a graph store at the given path.

The backend is chosen at runtime from the [graph] mode key of .recall-echo.toml in the parent directory (memory_dir): embedded (default) opens SurrealKV at path/surreal/; server connects to a SurrealDB server via the configured URL. The path is used for the FastEmbed models cache in both modes.

pub async fn open_embedded(path: &Path) -> Result<Self, GraphError>

Open the embedded SurrealKV store at path/surreal/.

pub async fn open_server(path: &Path) -> Result<Self, GraphError>

Connect to a SurrealDB server using [graph] settings from .recall-echo.toml in the parent directory (memory_dir). The path is still used for the FastEmbed models cache.

pub async fn connect( config: &ServerConfig, models_dir: &Path, ) -> Result<Self, GraphError>

Connect to a SurrealDB server over WebSocket with explicit config.

pub fn path(&self) -> &Path

Path to the graph store.

pub fn provenance_weights(&self) -> &ProvenanceWeights

Evidence weights this store applies to observations, by provenance class ([graph.provenance]).

pub async fn add_entity(&self, entity: NewEntity) -> Result<Entity, GraphError>

Add a new entity to the graph.

pub async fn get_entity(&self, name: &str) -> Result<Option<Entity>, GraphError>

Get an entity by name.

pub async fn get_entity_by_id( &self, id: &str, ) -> Result<Option<Entity>, GraphError>

Get an entity by its record ID.

pub async fn update_entity( &self, id: &str, updates: EntityUpdate, ) -> Result<Entity, GraphError>

Update an entity’s fields.

pub async fn delete_entity(&self, id: &str) -> Result<(), GraphError>

Delete an entity and its relationships.

pub async fn list_entities( &self, entity_type: Option<&str>, ) -> Result<Vec<Entity>, GraphError>

List all entities, optionally filtered by type.

pub async fn add_relationship( &self, rel: NewRelationship, ) -> Result<Relationship, GraphError>

Create a relationship between two named entities.

pub async fn get_relationships( &self, entity_name: &str, direction: Direction, ) -> Result<Vec<Relationship>, GraphError>

Get relationships for an entity.

pub async fn supersede_relationship( &self, old_id: &str, new: NewRelationship, ) -> Result<Relationship, GraphError>

Supersede a relationship: close the old one, create a new one.

pub async fn update_relationship_confidence( &self, rel_id: &str, confidence: f64, ) -> Result<(), GraphError>

Overwrite a relationship’s confidence, resetting its evidence to the prior around the new mean.

pub async fn reinforce_relationship( &self, rel_id: &str, evidence: EdgeEvidence, ) -> Result<(), GraphError>

Persist updated evidence for a relationship and reset its decay clock.

Called when a relationship is corroborated: the new posterior mean is stored as confidence, the coherence tally is stored beside it, and last_reinforced is set to now, preventing temporal decay from eroding the edge.

pub async fn add_episode( &self, episode: NewEpisode, ) -> Result<Episode, GraphError>

Add a new episode authored by the agent itself.

The conservative default: a caller that cannot say where the text came from must not have it counted as independent evidence. Ingestion, which does know, uses GraphMemory::add_episode_from.

pub async fn add_episode_from( &self, episode: NewEpisode, provenance: Provenance, ) -> Result<Episode, GraphError>

Add a new episode stamped with the class of whoever authored it.

pub async fn get_episodes_by_session( &self, session_id: &str, ) -> Result<Vec<Episode>, GraphError>

Get episodes by session ID.

pub async fn get_episode_by_log_number( &self, log_number: u32, ) -> Result<Option<Episode>, GraphError>

Get episode by log number.

pub async fn ingest_archive( &self, archive_text: &str, context: &IngestContext, llm: Option<&dyn LlmProvider>, ) -> Result<IngestionReport, GraphError>

Ingest a conversation archive into the knowledge graph.

The IngestContext carries the provenance policy: conversation archives infer per chunk from turn roles, document ingestion forces a class.

pub async fn extract_from_archive( &self, archive_text: &str, context: &IngestContext, llm: &dyn LlmProvider, ) -> Result<IngestionReport, GraphError>

Run LLM extraction on an archive without creating episodes.

pub async fn mark_extracted(&self, log_number: u32) -> Result<(), GraphError>

Mark all episodes with a given log_number as extracted.

pub async fn unextracted_log_numbers(&self) -> Result<Vec<i64>, GraphError>

Get log numbers of episodes that have NOT been extracted.

pub async fn search( &self, query: &str, limit: usize, ) -> Result<Vec<SearchResult>, GraphError>

Semantic search across entities (legacy — returns full Entity).

pub async fn search_with_options( &self, query: &str, options: &SearchOptions, ) -> Result<Vec<ScoredEntity>, GraphError>

Search with options — L1 projections, type/keyword filters.

pub async fn search_episodes( &self, query: &str, limit: usize, ) -> Result<Vec<EpisodeSearchResult>, GraphError>

Semantic search across episodes.

pub async fn query( &self, query_text: &str, options: &QueryOptions, ) -> Result<QueryResult, GraphError>

Hybrid query: semantic + graph expansion + optional episode search.

pub async fn traverse( &self, entity_name: &str, depth: u32, ) -> Result<TraversalNode, GraphError>

Traverse the graph from a named entity.

pub async fn traverse_filtered( &self, entity_name: &str, depth: u32, type_filter: Option<&str>, ) -> Result<TraversalNode, GraphError>

Traverse with type filter.

pub async fn sync_pipeline( &self, docs: &PipelineDocuments, ) -> Result<PipelineSyncReport, GraphError>

Sync pipeline documents into the graph.

pub async fn pipeline_stats( &self, staleness_days: u32, ) -> Result<PipelineGraphStats, GraphError>

Get pipeline stats from the graph.

pub async fn pipeline_entities( &self, stage: &str, status: Option<&str>, ) -> Result<Vec<EntityDetail>, GraphError>

Get pipeline entities by stage and optional status.

pub async fn pipeline_flow( &self, entity_name: &str, ) -> Result<Vec<(EntityDetail, String, EntityDetail)>, GraphError>

Trace pipeline flow for an entity.

pub async fn sync_vigil_signals( &self, signals_path: &Path, ) -> Result<VigilSyncReport, GraphError>

Sync vigil signal vectors into the graph as Measurement entities.

pub async fn sync_outcomes( &self, outcomes_path: &Path, ) -> Result<VigilSyncReport, GraphError>

Sync outcome records into the graph as Outcome entities.

pub async fn sync_vigil( &self, signals_path: &Path, outcomes_path: &Path, ) -> Result<VigilSyncReport, GraphError>

Sync both vigil signals and outcomes in one call.

pub async fn record_outcome_feedback( &self, session_id: &str, outcome: OutcomeKind, retrieved_entity_ids: &[String], used_entity_ids: Option<&[String]>, ) -> Result<FeedbackReport, GraphError>

Record outcome feedback: link retrieved entities to a session outcome and update their utility_score via EMA. used_entity_ids distinguishes the entities the response actually leaned on (full alpha) from retrieved-but- unused (muted alpha). Pass None to treat all retrieved as used.

pub async fn record_session_outcome( &self, session_id: &str, outcome: OutcomeKind, ) -> Result<FeedbackReport, GraphError>

Apply an outcome to every entity a session touched.

Resolves the session’s entities from the contributed_to records ingestion left behind (falling back to the entities the session authored), then records the outcome and moves their utility scores. The report says which entities moved and where they landed.

pub async fn record_session_use( &self, session_id: &str, entity_ids: &[String], ) -> Result<u32, GraphError>

Record that a session touched these entities, without judging it.

pub async fn run_gc(&self, config: &GcConfig) -> Result<GcReport, GraphError>

Run garbage collection with the given config.

pub async fn gc_stats(&self) -> Result<GcStatsReport, GraphError>

Get GC health stats without running collection.

pub async fn delete_relationship(&self, id: &str) -> Result<(), GraphError>

Delete a single relationship by ID.

pub async fn stats(&self) -> Result<GraphStats, GraphError>

Get graph statistics.