Trait SubstrateProvider 

pub trait SubstrateProvider: Send + Sync {
    // Required methods
    fn store_experience<'life0, 'async_trait>(
        &'life0 self,
        exp: NewExperience,
    ) -> Pin<Box<dyn Future<Output = Result<ExperienceId, PulseDBError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn get_experience<'life0, 'async_trait>(
        &'life0 self,
        id: ExperienceId,
    ) -> Pin<Box<dyn Future<Output = Result<Option<Experience>, PulseDBError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn search_similar<'life0, 'life1, 'async_trait>(
        &'life0 self,
        collective: CollectiveId,
        embedding: &'life1 [f32],
        k: usize,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<(Experience, f32)>, PulseDBError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn get_recent<'life0, 'async_trait>(
        &'life0 self,
        collective: CollectiveId,
        limit: usize,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<Experience>, PulseDBError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn store_relation<'life0, 'async_trait>(
        &'life0 self,
        rel: NewExperienceRelation,
    ) -> Pin<Box<dyn Future<Output = Result<RelationId, PulseDBError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn get_related<'life0, 'async_trait>(
        &'life0 self,
        exp_id: ExperienceId,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<(Experience, ExperienceRelation)>, PulseDBError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn store_insight<'life0, 'async_trait>(
        &'life0 self,
        insight: NewDerivedInsight,
    ) -> Pin<Box<dyn Future<Output = Result<InsightId, PulseDBError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn get_insights<'life0, 'life1, 'async_trait>(
        &'life0 self,
        collective: CollectiveId,
        embedding: &'life1 [f32],
        k: usize,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<(DerivedInsight, f32)>, PulseDBError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn get_activities<'life0, 'async_trait>(
        &'life0 self,
        collective: CollectiveId,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<Activity>, PulseDBError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn get_context_candidates<'life0, 'async_trait>(
        &'life0 self,
        request: ContextRequest,
    ) -> Pin<Box<dyn Future<Output = Result<ContextCandidates, PulseDBError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn watch<'life0, 'async_trait>(
        &'life0 self,
        collective: CollectiveId,
    ) -> Pin<Box<dyn Future<Output = Result<Pin<Box<dyn Stream<Item = WatchEvent> + Send>>, PulseDBError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn create_collective<'life0, 'life1, 'async_trait>(
        &'life0 self,
        name: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<CollectiveId, PulseDBError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn get_or_create_collective<'life0, 'life1, 'async_trait>(
        &'life0 self,
        name: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<CollectiveId, PulseDBError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn list_collectives<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<Collective>, PulseDBError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;

    // Provided methods
    fn list_experiences<'life0, 'async_trait>(
        &'life0 self,
        _collective: CollectiveId,
        _limit: usize,
        _offset: usize,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<Experience>, PulseDBError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn list_relations<'life0, 'async_trait>(
        &'life0 self,
        _collective: CollectiveId,
        _limit: usize,
        _offset: usize,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<ExperienceRelation>, PulseDBError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn list_insights<'life0, 'async_trait>(
        &'life0 self,
        _collective: CollectiveId,
        _limit: usize,
        _offset: usize,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<DerivedInsight>, PulseDBError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
}

Async storage interface for agent framework integration.

This trait abstracts PulseDB’s storage capabilities behind an async boundary, enabling agent frameworks to interact with the database without blocking the async runtime.

Object Safety

SubstrateProvider is object-safe via #[async_trait], allowing it to be used as Box<dyn SubstrateProvider> in any async context.

Implementors

• PulseDBSubstrate — production implementation wrapping Arc<PulseDB>

Required Methods

fn store_experience<'life0, 'async_trait>( &'life0 self, exp: NewExperience, ) -> Pin<Box<dyn Future<Output = Result<ExperienceId, PulseDBError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Stores a new experience and returns its assigned ID.

Generates an embedding (if configured), writes to storage, and indexes in the collective’s HNSW graph.

fn get_experience<'life0, 'async_trait>( &'life0 self, id: ExperienceId, ) -> Pin<Box<dyn Future<Output = Result<Option<Experience>, PulseDBError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Retrieves an experience by ID, or None if it doesn’t exist.

fn search_similar<'life0, 'life1, 'async_trait>( &'life0 self, collective: CollectiveId, embedding: &'life1 [f32], k: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<(Experience, f32)>, PulseDBError>> + Send + 'async_trait>>

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

Searches for experiences similar to the given embedding.

Returns up to k results as (Experience, similarity_score) tuples, sorted by similarity descending (1.0 = identical).

fn get_recent<'life0, 'async_trait>( &'life0 self, collective: CollectiveId, limit: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<Experience>, PulseDBError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Retrieves the most recent experiences from a collective.

Returns up to limit experiences sorted by timestamp descending.

fn store_relation<'life0, 'async_trait>( &'life0 self, rel: NewExperienceRelation, ) -> Pin<Box<dyn Future<Output = Result<RelationId, PulseDBError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Stores a relation between two experiences.

fn get_related<'life0, 'async_trait>( &'life0 self, exp_id: ExperienceId, ) -> Pin<Box<dyn Future<Output = Result<Vec<(Experience, ExperienceRelation)>, PulseDBError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Retrieves all experiences related to the given experience (both directions).

Returns (related_experience, relation) tuples for both outgoing and incoming relations.

fn store_insight<'life0, 'async_trait>( &'life0 self, insight: NewDerivedInsight, ) -> Pin<Box<dyn Future<Output = Result<InsightId, PulseDBError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Stores a derived insight synthesized from source experiences.

fn get_insights<'life0, 'life1, 'async_trait>( &'life0 self, collective: CollectiveId, embedding: &'life1 [f32], k: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<(DerivedInsight, f32)>, PulseDBError>> + Send + 'async_trait>>

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

Searches for insights similar to the given embedding.

Returns up to k results as (DerivedInsight, similarity_score) tuples.

fn get_activities<'life0, 'async_trait>( &'life0 self, collective: CollectiveId, ) -> Pin<Box<dyn Future<Output = Result<Vec<Activity>, PulseDBError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Retrieves active (non-stale) agent activities in a collective.

fn get_context_candidates<'life0, 'async_trait>( &'life0 self, request: ContextRequest, ) -> Pin<Box<dyn Future<Output = Result<ContextCandidates, PulseDBError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Assembles context candidates from all retrieval primitives.

Orchestrates similarity search, recent experiences, insights, relations, and active agents into a single response.

fn watch<'life0, 'async_trait>( &'life0 self, collective: CollectiveId, ) -> Pin<Box<dyn Future<Output = Result<Pin<Box<dyn Stream<Item = WatchEvent> + Send>>, PulseDBError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Subscribes to real-time experience change events in a collective.

Returns a Stream that yields WatchEvent values whenever experiences are created, updated, archived, or deleted.

fn create_collective<'life0, 'life1, 'async_trait>( &'life0 self, name: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<CollectiveId, PulseDBError>> + Send + 'async_trait>>

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

Creates a new collective (namespace).

Returns the new collective’s ID. Fails if a collective with the same name already exists.

fn get_or_create_collective<'life0, 'life1, 'async_trait>( &'life0 self, name: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<CollectiveId, PulseDBError>> + Send + 'async_trait>>

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

Gets an existing collective by name, or creates it if it doesn’t exist.

This is the recommended method for SDK consumers — idempotent and safe to call repeatedly with the same name.

fn list_collectives<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<Collective>, PulseDBError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Lists all collectives in the database.

Provided Methods

fn list_experiences<'life0, 'async_trait>( &'life0 self, _collective: CollectiveId, _limit: usize, _offset: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<Experience>, PulseDBError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Lists experiences in a collective with pagination.

Returns full Experience records including embeddings. Default implementation returns empty vec for backward compatibility.

fn list_relations<'life0, 'async_trait>( &'life0 self, _collective: CollectiveId, _limit: usize, _offset: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<ExperienceRelation>, PulseDBError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Lists relations in a collective with pagination.

Default implementation returns empty vec for backward compatibility.

fn list_insights<'life0, 'async_trait>( &'life0 self, _collective: CollectiveId, _limit: usize, _offset: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<DerivedInsight>, PulseDBError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Lists insights in a collective with pagination.

Default implementation returns empty vec for backward compatibility.

Implementors

impl SubstrateProvider for PulseDBSubstrate