Trait Memory 

pub trait Memory:
    Send
    + Sync
    + Attributable {
    // Required methods
    fn name(&self) -> &str;
    fn store<'life0, 'life1, 'life2, 'life3, 'async_trait>(
        &'life0 self,
        key: &'life1 str,
        content: &'life2 str,
        category: MemoryCategory,
        session_id: Option<&'life3 str>,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait;
    fn recall<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
        &'life0 self,
        query: &'life1 str,
        limit: usize,
        session_id: Option<&'life2 str>,
        since: Option<&'life3 str>,
        until: Option<&'life4 str>,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<MemoryEntry>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait,
             'life4: 'async_trait;
    fn get<'life0, 'life1, 'async_trait>(
        &'life0 self,
        key: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<Option<MemoryEntry>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn list<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        category: Option<&'life1 MemoryCategory>,
        session_id: Option<&'life2 str>,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<MemoryEntry>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;
    fn forget<'life0, 'life1, 'async_trait>(
        &'life0 self,
        key: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn forget_for_agent<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        key: &'life1 str,
        agent_id: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;
    fn count<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn health_check<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = bool> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn store_with_agent<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'async_trait>(
        &'life0 self,
        key: &'life1 str,
        content: &'life2 str,
        category: MemoryCategory,
        session_id: Option<&'life3 str>,
        namespace: Option<&'life4 str>,
        importance: Option<f64>,
        agent_id: Option<&'life5 str>,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait,
             'life4: 'async_trait,
             'life5: 'async_trait;
    fn recall_for_agents<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'life6, 'async_trait>(
        &'life0 self,
        allowed_agent_ids: &'life1 [&'life2 str],
        query: &'life3 str,
        limit: usize,
        session_id: Option<&'life4 str>,
        since: Option<&'life5 str>,
        until: Option<&'life6 str>,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<MemoryEntry>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait,
             'life4: 'async_trait,
             'life5: 'async_trait,
             'life6: 'async_trait;

    // Provided methods
    fn get_for_agent<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        key: &'life1 str,
        agent_id: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<Option<MemoryEntry>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn purge_namespace<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _namespace: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn purge_session<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _session_id: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn purge_session_for_agent<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _session_id: &'life1 str,
        _agent_id: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn purge_agent<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _agent_alias: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn export_agent<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _agent_alias: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<MemoryEntry>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn rename_agent<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _from: &'life1 str,
        _to: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn count_agent<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _agent_alias: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn supersede<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _superseded_ids: &'life1 [String],
        _new_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 { ... }
    fn store_procedural<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _messages: &'life1 [ProceduralMessage],
        _session_id: Option<&'life2 str>,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn count_in_scope<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _namespace: Option<&'life1 str>,
        _category: Option<&'life2 MemoryCategory>,
    ) -> Pin<Box<dyn Future<Output = Result<u64>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn stats<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<MemoryStats>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn reindex<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn refresh_embedder(
        &self,
        _model_provider: &str,
        _api_key: Option<&str>,
        _model: &str,
        _dimensions: usize,
    ) { ... }
    fn recall_namespaced<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'async_trait>(
        &'life0 self,
        namespace: &'life1 str,
        query: &'life2 str,
        limit: usize,
        session_id: Option<&'life3 str>,
        since: Option<&'life4 str>,
        until: Option<&'life5 str>,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<MemoryEntry>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait,
             'life4: 'async_trait,
             'life5: 'async_trait { ... }
    fn export<'life0, 'life1, 'async_trait>(
        &'life0 self,
        filter: &'life1 ExportFilter,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<MemoryEntry>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn store_with_metadata<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
        &'life0 self,
        key: &'life1 str,
        content: &'life2 str,
        category: MemoryCategory,
        session_id: Option<&'life3 str>,
        _namespace: Option<&'life4 str>,
        _importance: Option<f64>,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait,
             'life4: 'async_trait { ... }
    fn store_with_options<'life0, 'life1, 'life2, 'life3, 'async_trait>(
        &'life0 self,
        key: &'life1 str,
        content: &'life2 str,
        category: MemoryCategory,
        session_id: Option<&'life3 str>,
        options: StoreOptions,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait { ... }
    fn store_with_options_and_agent<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
        &'life0 self,
        key: &'life1 str,
        content: &'life2 str,
        category: MemoryCategory,
        session_id: Option<&'life3 str>,
        options: StoreOptions,
        agent_id: Option<&'life4 str>,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait,
             'life4: 'async_trait { ... }
    fn ensure_agent_uuid<'life0, 'life1, 'async_trait>(
        &'life0 self,
        alias: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
}

Core memory trait — implement for any persistence backend

Required Methods

fn name(&self) -> &str

Backend name

fn store<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, key: &'life1 str, content: &'life2 str, category: MemoryCategory, session_id: Option<&'life3 str>, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

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

Store a memory entry, optionally scoped to a session

fn recall<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, query: &'life1 str, limit: usize, session_id: Option<&'life2 str>, since: Option<&'life3 str>, until: Option<&'life4 str>, ) -> Pin<Box<dyn Future<Output = Result<Vec<MemoryEntry>>> + Send + 'async_trait>>

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

Recall memories matching a query (keyword search), optionally scoped to a session and time range. Empty, whitespace-only, and bare “” queries return recent/time-only entries. Non-bare wildcard terms such as “wild” remain keyword queries. Time bounds use RFC 3339 / ISO 8601 format (e.g. “2025-03-01T00:00:00Z”); inclusive (created_at >= since, created_at <= until).

fn get<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<MemoryEntry>>> + Send + 'async_trait>>

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

Get a specific memory by key.

After composite uniqueness landed, multiple rows may share a key (one per agent). This method returns some matching row without an agent filter; callers that need an agent-scoped lookup use get_for_agent.

fn list<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, category: Option<&'life1 MemoryCategory>, session_id: Option<&'life2 str>, ) -> Pin<Box<dyn Future<Output = Result<Vec<MemoryEntry>>> + Send + 'async_trait>>

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

List all memory keys, optionally filtered by category and/or session

fn forget<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>

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

Remove a memory by key. Deletes every row matching key, regardless of agent attribution. Agent-scoped callers (the AgentScopedMemory wrapper) use forget_for_agent instead.

fn forget_for_agent<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, key: &'life1 str, agent_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>

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

Remove the row matching (key, agent_id). Siblings of the same key under other agents are untouched. Returns true if a row was removed. Required: no safe default exists for backends or wrappers that can hold more than one row per key — the unscoped forget would destroy sibling rows.

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

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

Count total memories

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

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

Health check

fn store_with_agent<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'async_trait>( &'life0 self, key: &'life1 str, content: &'life2 str, category: MemoryCategory, session_id: Option<&'life3 str>, namespace: Option<&'life4 str>, importance: Option<f64>, agent_id: Option<&'life5 str>, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

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

Store a memory entry attributed to an explicit agent UUID. Every backend must implement this explicitly so the agent_id is never silently dropped at storage time. Backends with native agent_id columns (SqliteMemory, PostgresMemory, LucidMemory) persist the attribution in SQL; MarkdownMemory attributes via the per-agent directory path; QdrantMemory persists in the vector payload; NoneMemory is a no-op stub. AgentScopedMemory is the canonical caller.

fn recall_for_agents<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'life6, 'async_trait>( &'life0 self, allowed_agent_ids: &'life1 [&'life2 str], query: &'life3 str, limit: usize, session_id: Option<&'life4 str>, since: Option<&'life5 str>, until: Option<&'life6 str>, ) -> Pin<Box<dyn Future<Output = Result<Vec<MemoryEntry>>> + Send + 'async_trait>>

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

Recall memory entries scoped to a specific set of agent UUIDs. When allowed_agent_ids is non-empty, the backend filters its result set to rows whose agent_id matches one of the listed UUIDs (or is NULL, for legacy rows written before the agent_id column existed). Every backend must implement this explicitly so the allowlist is never silently dropped at read time.

For SQL-backed stores the filter is WHERE agent_id IN (...). For Markdown the implementation walks the allowed agents’ per-agent directories. For Qdrant it’s a payload filter on the agent_id field. For None it returns an empty list. AgentScopedMemory is the canonical caller; direct invocation is also valid for read-only cross-agent queries that bypass the wrapper.

Cross-backend allowlist entries are rejected at config load (agents.<alias>.workspace.read_memory_from cannot point at a sibling on a different memory backend); backends therefore never need to handle a cross-backend recall.

Provided Methods

fn get_for_agent<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, key: &'life1 str, agent_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<Option<MemoryEntry>>> + Send + 'async_trait>>

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

Get the memory row matching (key, agent_id). Siblings of the same key under other agents are invisible.

The default implementation composes get with an agent_id filter and is only correct for backends whose storage layout cannot hold more than one row per key (markdown’s per-agent dir scheme, the none stub). Backends that can hold multiple rows per key (SQL with composite unique, Qdrant) override this with a native composite lookup.

fn purge_namespace<'life0, 'life1, 'async_trait>( &'life0 self, _namespace: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>

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

Remove all memories whose namespace field equals the given value. Returns the number of deleted entries. Default: returns unsupported error. Backends that support bulk deletion override this.

fn purge_session<'life0, 'life1, 'async_trait>( &'life0 self, _session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>

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

Remove all memories in a session. Returns the number of deleted entries. Default: returns unsupported error. Backends that support bulk deletion override this.

fn purge_session_for_agent<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _session_id: &'life1 str, _agent_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>

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

Remove all memories in a session for one agent. Returns the number of deleted entries. Default: returns unsupported error. Backends with per-agent storage override this; agent-scoped wrappers use it instead of composing a session list with key-only deletes.

fn purge_agent<'life0, 'life1, 'async_trait>( &'life0 self, _agent_alias: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>

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

Remove every memory row attributed to the given agent alias. Returns the number of deleted entries. Called when an agent alias is removed from [agents.<alias>] so the database doesn’t accumulate rows for retired aliases. Default: returns unsupported error. Backends with per-agent storage (sqlite, postgres) override this; backends without (markdown, none) keep the default and the caller logs a warning.

fn export_agent<'life0, 'life1, 'async_trait>( &'life0 self, _agent_alias: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Vec<MemoryEntry>>> + Send + 'async_trait>>

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

Export every memory row attributed to agent_alias, for the agent- deletion archive (export-then-delete,). Pairs with Self::purge_agent: the surface exports these rows to the archive, then purges. Default: empty (backends without per-agent export).

fn rename_agent<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _from: &'life1 str, _to: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>

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

Re-point every memory row from the from alias to the to alias, returning the number of rows re-pointed. Called when an alias is renamed. For the SQL backends (sqlite/postgres) memory rows ride the agent’s UUID, so this is a single UPDATE agents SET alias and the count is the agents-row count (0 or 1); payload-keyed backends (qdrant) rewrite the alias on every matching memory point and return that count. Default: unsupported error; backends with per-agent storage override. Markdown/none keep the default and the caller logs a warning.

fn count_agent<'life0, 'life1, 'async_trait>( &'life0 self, _agent_alias: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>

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

Read-only residue probe for the agent-rename cascade: the count of state Self::rename_agent WOULD re-point for agent_alias, without mutating anything. Used by the gateway to tell a genuine post-persist partial failure (state still lagging at the old alias) apart from an unrelated request, so a resume only fires on real residue.

MUST mirror exactly what rename_agent moves: for the SQL backends that is the agents row (alias presence), NOT the memory-row count - an agent with an agents row but zero memory rows still gets re-pointed, so a memory-row probe would be a false negative. Default 0 (markdown/none have no DB rows and their rename_agent is a no-op).

fn supersede<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _superseded_ids: &'life1 [String], _new_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,

Mark entries as superseded by a newer row.

Default: no-op. SQL backends can override this with reversible soft-hide behavior; non-SQL backends remain source-compatible.

fn store_procedural<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _messages: &'life1 [ProceduralMessage], _session_id: Option<&'life2 str>, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

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

Store a procedural “how to” trace from a tool-calling turn.

Default: no-op. Backends that support procedural storage can override.

fn count_in_scope<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _namespace: Option<&'life1 str>, _category: Option<&'life2 MemoryCategory>, ) -> Pin<Box<dyn Future<Output = Result<u64>> + Send + 'async_trait>>

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

Count rows within a namespace/category scope.

Default is zero so quota enforcement remains opt-in until a backend provides an efficient implementation.

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

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

Read-side memory store telemetry.

Default is empty telemetry so status consumers can be introduced before every backend has native stats support.

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

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

Rebuild backend indexes: FTS tables and any missing embedding vectors.

Intended as a manual fixup after bulk writes that didn’t go through the normal store() path (e.g. zeroclaw migrate openclaw, which uses NoopEmbedding for speed and leaves embedding = NULL behind). Returns the number of entries that were re-embedded; backends without a vector index or with nothing to fill in return 0.

Default: no-op. Overridden by backends that maintain separate derived indexes (e.g. SqliteMemory).

fn refresh_embedder( &self, _model_provider: &str, _api_key: Option<&str>, _model: &str, _dimensions: usize, )

Hot-swap the embedding provider after a config/set provider-profile change, so a long-lived memory handle (e.g. the install-wide RPC memory handle) stops using stale endpoint/key values without a daemon restart.

The arguments are the already-resolved embedding settings — the literal provider (openai / openrouter / custom:<url>), key, model, and dimensions produced by the memory crate’s embedding resolver from the canonical config. The impl rebuilds its embedder from them and swaps it in place; no provider state is duplicated into a separate cache.

Default: no-op. Backends that do not embed, or cannot swap their embedder in place, keep the default.

fn recall_namespaced<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'async_trait>( &'life0 self, namespace: &'life1 str, query: &'life2 str, limit: usize, session_id: Option<&'life3 str>, since: Option<&'life4 str>, until: Option<&'life5 str>, ) -> Pin<Box<dyn Future<Output = Result<Vec<MemoryEntry>>> + Send + 'async_trait>>

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

Recall memories scoped to a specific namespace.

Default implementation delegates to recall() and filters by namespace. Backends with native namespace support should override for efficiency.

fn export<'life0, 'life1, 'async_trait>( &'life0 self, filter: &'life1 ExportFilter, ) -> Pin<Box<dyn Future<Output = Result<Vec<MemoryEntry>>> + Send + 'async_trait>>

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

Bulk-export memories matching the given filter criteria.

Intended for GDPR Art. 20 data portability. Returns entries ordered by creation time (ascending). Embeddings are excluded.

Default implementation delegates to list() and post-filters on namespace and time range. Backends with native query support should override for efficiency.

fn store_with_metadata<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, key: &'life1 str, content: &'life2 str, category: MemoryCategory, session_id: Option<&'life3 str>, _namespace: Option<&'life4 str>, _importance: Option<f64>, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

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

Store a memory entry with namespace and importance.

Default implementation delegates to store(). Backends with native namespace/importance support should override.

fn store_with_options<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, key: &'life1 str, content: &'life2 str, category: MemoryCategory, session_id: Option<&'life3 str>, options: StoreOptions, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

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

Store a memory entry with the full additive metadata surface.

Default delegates through the existing metadata method for namespace and importance only. Backends that do not override this must fail explicitly when callers pass typed/full metadata, rather than silently discarding data needed by later typed-memory readers.

fn store_with_options_and_agent<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, key: &'life1 str, content: &'life2 str, category: MemoryCategory, session_id: Option<&'life3 str>, options: StoreOptions, agent_id: Option<&'life4 str>, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

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

Store a memory entry with full metadata and an explicit agent UUID.

The compatibility default preserves agent attribution through the established store_with_agent path for namespace and importance only. Backends that persist the full StoreOptions surface override this method so wrappers do not have to choose between attribution and typed metadata.

fn ensure_agent_uuid<'life0, 'life1, 'async_trait>( &'life0 self, alias: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<String>> + Send + 'async_trait>>

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

Look up (or create) the identifier the backend uses to refer to the agent named by alias.

Backends with an agents table (SqliteMemory, PostgresMemory, LucidMemory) return the row’s UUID, inserting if absent. Backends without (MarkdownMemory, QdrantMemory, NoneMemory) return the alias verbatim — there is no UUID indirection at the storage layer, so the alias serves as the agent_id. Default impl returns the alias unchanged; SQL backends override to do the real lookup.

Implementors