Struct LucidMemory 

pub struct LucidMemory { /* private fields */ }

Implementations

impl LucidMemory

pub fn new( alias: &str, workspace_dir: &Path, local: SqliteMemory, ) -> LucidMemory

pub fn with_overrides( alias: &str, workspace_dir: &Path, local: SqliteMemory, lucid_cmd: Option<String>, recall_timeout_ms: Option<u64>, store_timeout_ms: Option<u64>, ) -> LucidMemory

Construct with config-sourced overrides ([storage.lucid.<alias>]). Each None falls back to the built-in default, so an unconfigured alias behaves exactly like Self::new. Explicit blank commands stay invalid instead of falling through to PATH; zero deadlines fall back because normal config loading warns and keeps the process available for operator repair after validation errors.

pub fn embedder_dimensions(&self) -> usize

Dimensions of the underlying local SQLite embedder (0 = Noop). Lets callers confirm a live embedder refresh reached the local backend

Trait Implementations

impl Attributable for LucidMemory

fn role(&self) -> Role

fn alias(&self) -> &str

impl Memory for LucidMemory

fn name(&self) -> &str

Backend name

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.

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<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, LucidMemory: '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>, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, LucidMemory: '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>, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, LucidMemory: 'async_trait,

Get a specific memory by key.

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>, Error>> + Send + 'async_trait>>

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

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

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>, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, LucidMemory: '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, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, LucidMemory: '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, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, LucidMemory: '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 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, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, LucidMemory: '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, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, LucidMemory: '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>, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, LucidMemory: '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, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, LucidMemory: '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, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, LucidMemory: '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.

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

where 'life0: 'async_trait, LucidMemory: 'async_trait,

Count total memories

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

where 'life0: 'async_trait, LucidMemory: '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<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, 'life5: 'async_trait, LucidMemory: '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>, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, 'life5: 'async_trait, 'life6: 'async_trait, LucidMemory: '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.

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

where 'life0: 'async_trait, 'life1: 'async_trait, LucidMemory: 'async_trait,

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

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

where 'life0: 'async_trait, 'life1: 'async_trait, Self: '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, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, Self: '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 supersede<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _superseded_ids: &'life1 [String], _new_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

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

Mark entries as superseded by a newer row.

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

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

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

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, Error>> + Send + 'async_trait>>

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

Count rows within a namespace/category scope.

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

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

Read-side memory store telemetry.

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

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

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

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>, Error>> + Send + 'async_trait>>

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

Recall memories scoped to a specific namespace.

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

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

Bulk-export memories matching the given filter criteria.

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<(), Error>> + Send + 'async_trait>>

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

Store a memory entry with namespace and importance.

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<(), Error>> + Send + 'async_trait>>

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

Store a memory entry with the full additive metadata surface.

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<(), Error>> + Send + 'async_trait>>

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

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