Struct SurrealStore 

pub struct SurrealStore { /* private fields */ }

A SurrealDB-backed Store.

Implementations

impl SurrealStore

pub async fn open_embedded() -> Result<Self>

Opens an in-memory embedded store (the Mem engine), with no embedder. Use for tests; data does not survive restart.

Errors

Returns IjimaError::Store if SurrealDB cannot initialize.

pub async fn open_embedded_with(embedder: Arc<dyn Embedder>) -> Result<Self>

Opens an in-memory embedded store with an Embedder.

Errors

Returns IjimaError::Store if SurrealDB cannot initialize.

pub async fn open_persistent(path: impl AsRef<Path>) -> Result<Self>

Opens a persistent store (the SurrealKv engine) at path, with no embedder. Data survives restart. Creates the directory if absent.

Errors

Returns IjimaError::Store if SurrealDB cannot initialize or the path is unwritable.

pub async fn open_persistent_with( path: impl AsRef<Path>, embedder: Arc<dyn Embedder>, ) -> Result<Self>

Opens a persistent store with an Embedder.

Errors

Returns IjimaError::Store if SurrealDB cannot initialize or the path is unwritable.

pub async fn export_to(&self, path: impl AsRef<Path>) -> Result<()>

Exports the entire store as a SurrealDB SQL dump to path. Requires a persistent backend (SurrealKv); in-memory stores do not support Backup.

Trait Implementations

impl KnowledgeGraph for SurrealStore

fn add_triple<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, subject: EntityId, predicate: &'life2 str, object: EntityId, valid_from: Option<&'life3 str>, confidence: f32, source_memory_id: Option<&'life4 str>, ) -> Pin<Box<dyn Future<Output = Result<Triple>> + Send + 'async_trait>>

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

Adds (or refreshes) the subject + object entities and creates a triple edge between them. Returns the created Triple.

fn query_entity<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, entity: &'life2 EntityId, ) -> Pin<Box<dyn Future<Output = Result<EntityRecord>> + Send + 'async_trait>>

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

Returns an entity and all its connected triples (outgoing + incoming) within ns.

fn invalidate_triple<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, triple_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

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

Marks a triple as no longer current by setting valid_to. Idempotent.

fn find_triples<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, subject: Option<&'life2 EntityId>, predicate: Option<&'life3 str>, object: Option<&'life4 EntityId>, ) -> Pin<Box<dyn Future<Output = Result<Vec<Triple>>> + Send + 'async_trait>>

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

Finds triples matching any combination of subject / predicate / object (None = wildcard).

fn kg_timeline<'life0, 'life1, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, limit: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<Triple>>> + Send + 'async_trait>>

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

Returns triples in chronological order (by valid_from), most recent first.

fn knowledge_stats<'life0, 'life1, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, ) -> Pin<Box<dyn Future<Output = Result<KgStats>> + Send + 'async_trait>>

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

Entity + triple counts for ns.

fn kg_global_stats<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<KgStats>> + Send + 'async_trait>>

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

Global entity + triple counts across all namespaces.

impl Store for SurrealStore

fn store_memory<'life0, 'life1, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, memory: Memory, ) -> Pin<Box<dyn Future<Output = Result<MemoryId>> + Send + 'async_trait>>

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

Stores a curated memory under ns, performing content-hash + semantic dedup. Returns the stored id.

fn check_duplicate<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, content: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<Option<MemoryId>>> + Send + 'async_trait>>

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

Checks whether a memory with identical content already exists in ns (content-hash dedup). Returns the existing MemoryId if so.

fn recall_memory<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, id: &'life2 MemoryId, ) -> Pin<Box<dyn Future<Output = Result<Option<Memory>>> + Send + 'async_trait>>

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

Recalls a single memory by id within ns. Returns None if the id is absent or belongs to a different namespace (isolation).

fn delete_memory<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, id: &'life2 MemoryId, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

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

Deletes a memory by id within ns.

fn list_memories<'life0, 'life1, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, limit: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<Memory>>> + Send + 'async_trait>>

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

Lists up to limit memories in ns, ranked by importance DESC then recency DESC. Powers wake-up composition (L1a personal essentials, L1b doctrine baseline).

fn store_stats<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<StoreStats>> + Send + 'async_trait>>

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

Global store statistics across all namespaces (operator/admin view). Powers GET /status.

fn list_rooms<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, project: Option<&'life2 str>, limit: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<Room>>> + Send + 'async_trait>>

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

Lists rooms (topic cells) in ns, optionally filtered to a single project. Each room carries its memory count. Ordered by count desc.

fn taxonomy<'life0, 'life1, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, ) -> Pin<Box<dyn Future<Output = Result<Vec<ProjectTaxon>>> + Send + 'async_trait>>

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

Full project → topic → count taxonomy of ns. Powers getTaxonomy navigation.

fn palace_graph<'life0, 'life1, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, ) -> Pin<Box<dyn Future<Output = Result<PalaceGraph>> + Send + 'async_trait>>

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

The palace graph: projects as nodes, shared-topic tunnels as edges. Powers getPalaceGraph — “what connects these projects?”

fn traverse_tunnel<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, topic: &'life2 str, project_a: &'life3 str, project_b: &'life4 str, limit: usize, ) -> Pin<Box<dyn Future<Output = Result<TunnelTraversal>> + Send + 'async_trait>>

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

Traverses a tunnel: returns the actual memories from both projects on the shared topic, so the caller can see what connects them.

fn search_memories<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, embedding: &'life2 Embedding, limit: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<SearchHit>>> + Send + 'async_trait>>

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

Semantic search over memories in ns by nearest embedding.

fn ingest_turn<'life0, 'life1, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, turn: SessionTurn, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

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

Appends a raw turn to the session transcript under ns.

fn session_turns<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, session: &'life2 SessionId, limit: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<SessionTurn>>> + Send + 'async_trait>>

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

Returns the last limit turns of session under ns, in order.

fn create_session<'life0, 'life1, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, session: Session, ) -> Pin<Box<dyn Future<Output = Result<SessionId>> + Send + 'async_trait>>

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

Creates or updates a session’s metadata under ns (upsert by id). Call when a session starts; turns reference the session id. ended_at is set via Self::end_session.

fn list_sessions<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, harness: Option<&'life2 Harness>, limit: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<Session>>> + Send + 'async_trait>>

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

Lists up to limit sessions in ns, newest first, optionally filtered by harness.

fn end_session<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, session: &'life2 SessionId, ended_at: String, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

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

Marks a session as ended (sets ended_at). Scoped by ns so a principal can only end sessions in their own namespace.

fn enqueue_extraction<'life0, 'life1, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, memory: Memory, confidence: f32, ) -> Pin<Box<dyn Future<Output = Result<String>> + Send + 'async_trait>>

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

Stages a PendingReview extraction in the per-namespace queue.

fn list_pending<'life0, 'life1, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, limit: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<QueuedExtraction>>> + Send + 'async_trait>>

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

Lists pending extractions in ns, newest first.

fn accept_extraction<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, queue_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<AcceptedExtraction>> + Send + 'async_trait>>

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

Accepts a queued extraction: promotes it to the palace and removes it from the queue.

fn reject_extraction<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, queue_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

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

Rejects a queued extraction: drops it from the queue without promoting.

fn write_diary<'life0, 'life1, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, entry: DiaryEntry, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

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

Appends a diary entry under ns.

fn read_diary<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, agent: &'life2 str, limit: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<DiaryEntry>>> + Send + 'async_trait>>

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

Returns the last limit entries of agent’s diary under ns, in chronological order.

fn register_repo<'life0, 'async_trait>( &'life0 self, repo: RepoDirectory, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

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

Registers or upserts a repository in the global registry (keyed by name). Powers POST /repos — the canonical Anima roster.

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

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

Lists every registered repository (the ecosystem roster).

fn list_memories_filtered<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, ns: &'life1 NamespaceId, project: Option<&'life2 str>, topic: Option<&'life3 str>, limit: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<Memory>, IjimaError>> + Send + 'async_trait>>

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

Lists memories in ns, optionally filtered to project/topic. Powers GET /memories (the memory_recall browse path — distinct from Self::list_memories, which is the importance-ranked wake-up feed). Default: fetch a cap, filter in Rust, truncate. Backends MAY override with a native filtered query.

fn resolve_repo<'life0, 'life1, 'async_trait>( &'life0 self, cwd: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<RepoDirectory>, IjimaError>> + Send + 'async_trait>>

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

Reverse-resolves a working directory to its registered repo: the most specific repo whose path is a prefix of cwd (after normalizing). Powers GET /repos/resolve (CWD → project).