Struct MemoryService 

pub struct MemoryService { /* private fields */ }

Facade over SurrealStorage with scope-aware helpers.

Implementations

impl MemoryService

pub async fn new(config: MemoryConfig) -> Result<Self>

Initialise the service by connecting to (or creating) the embedded SurrealDB store.

pub async fn add( &self, content: impl Into<String>, scope: MemoryScope, memory_type: MemoryType, user_ctx: &UserContext, agent_id: Option<&str>, session_id: Option<&str>, categories: Vec<String>, metadata: Option<Value>, importance: f32, ) -> Result<Memory>

Add a memory with explicit scope. User-scoped memories require user_ctx.user_id.

pub async fn search( &self, query: &str, user_ctx: &UserContext, agent_id: Option<&str>, session_id: Option<&str>, limit: usize, categories: Option<&[String]>, ) -> Result<Vec<Memory>>

Semantic search over scoped memories. Automatically filters by user ownership.

pub async fn hybrid_search( &self, query: &str, user_ctx: &UserContext, agent_id: Option<&str>, session_id: Option<&str>, limit: usize, vector_weight: Option<f32>, bm25_weight: Option<f32>, ) -> Result<Vec<Memory>>

Hybrid BM25 + HNSW vector search. Weights are read from config by default.

pub async fn auto_capture( &self, messages: Vec<Value>, user_ctx: &UserContext, agent_id: Option<&str>, session_id: Option<&str>, ) -> Result<Vec<Memory>>

Auto-extract memories from a conversation turn (calls the embedding LLM internally).

pub async fn list( &self, user_ctx: &UserContext, agent_id: Option<&str>, session_id: Option<&str>, ) -> Result<Vec<Memory>>

List all memories for a scope, filtered by caller identity.

pub async fn add_workflow_mirror_record( &self, record: WorkflowMirrorRecord, user_ctx: &UserContext, ) -> Result<Memory>

Add a KBD/OpenSpec workflow mirror record through the memory service boundary.

pub async fn list_workflow_mirror_candidates( &self, user_ctx: &UserContext, ) -> Result<Vec<WorkflowMirrorCandidate>>

List workflow mirror recovery candidates from scoped memory records.

pub async fn get(&self, id: &str) -> Result<Option<Memory>>

Retrieve a single memory by its record ID string (e.g. "memory:abc123").

pub async fn update(&self, id: &str, content: String) -> Result<Memory>

Update a memory’s content (creates a history record).

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

Delete a single memory. Ownership is not enforced here — callers should validate ownership before calling (e.g. via get + scope check).

pub async fn delete_all( &self, user_ctx: &UserContext, agent_id: Option<&str>, session_id: Option<&str>, ) -> Result<u64>

Delete all memories for a scope filter.

pub async fn history(&self, memory_id: &str) -> Result<Vec<MemoryHistory>>

Get the audit history for a memory.

pub async fn compress( &self, user_ctx: &UserContext, agent_id: Option<&str>, session_id: Option<&str>, older_than_days: u32, ) -> Result<Option<Memory>>

Compress memories older than older_than_days into a single summary.

pub async fn expire_stale(&self) -> Result<u64>

Expire stale memories (those past their valid_until TTL). Returns expired count.

pub async fn knowledge_graph(&self) -> Result<KnowledgeGraph>

pub async fn create_entity(&self, entity: Entity) -> Result<Entity>

pub async fn create_entities( &self, entities: Vec<Entity>, ) -> Result<Vec<Entity>>

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

pub async fn search_entities(&self, query: &str) -> Result<Vec<Entity>>

pub async fn semantic_search_entities( &self, query: &str, limit: usize, threshold: f32, ) -> Result<Vec<SemanticSearchResult>>

pub async fn add_entity_observations( &self, name: &str, observations: Vec<String>, ) -> Result<Entity>

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

pub async fn create_relation(&self, relation: Relation) -> Result<Relation>

pub async fn create_relations( &self, relations: Vec<Relation>, ) -> Result<Vec<Relation>>

pub async fn get_relations(&self, entity_name: &str) -> Result<Vec<Relation>>

pub async fn delete_relation( &self, from: &str, to: &str, relation_type: &str, ) -> Result<()>

pub async fn expand_neighbors( &self, entity_name: &str, depth: u8, limit: usize, ) -> Result<KnowledgeGraph>

pub async fn find_path( &self, from: &str, to: &str, max_depth: u8, ) -> Result<Vec<Vec<String>>>

pub async fn get_related( &self, entity_name: &str, relation_type: Option<&str>, direction: &str, limit: usize, ) -> Result<Vec<Entity>>

pub async fn create_task_stream(&self, stream: TaskStream) -> Result<TaskStream>

pub async fn get_task_stream( &self, name: &str, user_id: Option<&str>, agent_id: Option<&str>, ) -> Result<Option<TaskStream>>

pub async fn add_to_task_stream( &self, stream_name: &str, user_id: Option<&str>, agent_id: Option<&str>, memory: Memory, ) -> Result<Memory>

pub async fn task_stream_context( &self, stream_name: &str, user_id: Option<&str>, agent_id: Option<&str>, model_id: &str, max_tokens: Option<u64>, ) -> Result<ContextWindow>

Get a model-aware context window for a TaskStream, respecting the token budget.

pub async fn list_task_streams( &self, agent_id: Option<&str>, user_id: Option<&str>, ) -> Result<Vec<TaskStream>>

pub async fn archive_task_stream( &self, name: &str, user_id: Option<&str>, agent_id: Option<&str>, ) -> Result<TaskStream>

pub async fn auto_summarize_task_stream( &self, stream_name: &str, user_id: Option<&str>, agent_id: Option<&str>, model_id: &str, ) -> Result<Option<Memory>>

pub async fn create_mindmap(&self, mindmap: MindMap) -> Result<MindMap>

pub async fn get_mindmap( &self, name: &str, user_id: Option<&str>, ) -> Result<Option<MindMap>>

pub async fn list_mindmaps( &self, user_id: Option<&str>, agent_id: Option<&str>, ) -> Result<Vec<MindMap>>

pub async fn add_mindmap_node( &self, mindmap_name: &str, user_id: Option<&str>, node: MindMapNode, ) -> Result<MindMap>

pub async fn add_mindmap_edge( &self, mindmap_name: &str, user_id: Option<&str>, edge: MindMapEdge, ) -> Result<MindMap>

pub async fn delete_mindmap_node( &self, mindmap_name: &str, user_id: Option<&str>, node_id: &str, ) -> Result<MindMap>

pub async fn delete_mindmap( &self, name: &str, user_id: Option<&str>, ) -> Result<()>

pub fn storage(&self) -> Arc<dyn MemoryStorage>

Return the underlying storage for direct use in the MCP server handler.

pub fn config(&self) -> &MemoryConfig

Config accessor.

Trait Implementations

impl Clone for MemoryService

fn clone(&self) -> MemoryService

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MemoryService

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.