Struct MemoryConfig 

pub struct MemoryConfig {

    pub backend: String,
    pub auto_save: bool,
    pub hygiene_enabled: bool,
    pub consolidation_extract_facts: bool,
    pub archive_after_days: u32,
    pub purge_after_days: u32,
    pub conversation_retention_days: u32,
    pub daily_retention_days: u32,
    pub core_retention_days: u32,
    pub embedding_provider: String,
    pub embedding_model: String,
    pub embedding_dimensions: usize,
    pub auto_reindex_on_identity_change: bool,
    pub embedding_api_key: Option<String>,
    pub vector_weight: f64,
    pub keyword_weight: f64,
    pub search_mode: SearchMode,
    pub min_relevance_score: f64,
    pub embedding_cache_size: usize,
    pub chunk_max_tokens: usize,
    pub response_cache_enabled: bool,
    pub response_cache_ttl_minutes: u32,
    pub response_cache_max_entries: usize,
    pub response_cache_hot_entries: usize,
    pub snapshot_enabled: bool,
    pub snapshot_on_hygiene: bool,
    pub auto_hydrate: bool,
    pub retrieval_stages: Vec<String>,
    pub candidate_multiplier: usize,
    pub rerank_enabled: bool,
    pub rerank_threshold: usize,
    pub rerank_strategy: String,
    pub mmr_lambda: f64,
    pub importance_weight: f64,
    pub recency_weight: f64,
    pub fts_early_return_score: f64,
    pub default_namespace: String,
    pub conflict_threshold: f64,
    pub conflict_supersede_enabled: bool,
    pub dedup_on_write: bool,
    pub dedup_jaccard_threshold: f64,
    pub dedup_action: MemoryDedupAction,
    pub core_max_rows: u64,
    pub core_max_bytes: u64,
    pub daily_max_rows: u64,
    pub evict_order: MemoryEvictOrder,
    pub pin_namespaces: Vec<String>,
    pub pin_min_importance: f64,
    pub audit_enabled: bool,
    pub audit_retention_days: u32,
    pub policy: MemoryPolicyConfig,
    pub types: MemoryTypesConfig,
}

Memory backend configuration ([memory] section).

Controls conversation memory storage, embeddings, hybrid search, response caching, and memory snapshot/hydration. Backend-specific connection settings live under [storage.<backend>.<alias>]; this section selects which storage instance to use via the backend dotted reference.

Fields

backend: String

Dotted reference to the active storage instance: <backend>.<alias> (e.g. "sqlite.default", "postgres.work"). Resolves through Config.storage.<backend>.<alias> at runtime. Bare backend names ("sqlite") are treated as "<backend>.default". Set to "none" to disable persistence entirely.

auto_save: bool

Auto-save what you tell ZeroClaw into memory as conversation history — the agent’s own replies are not saved. Turn off if you want memory to only hold things you explicitly record via the memory tool.

hygiene_enabled: bool

Run the periodic hygiene pass that archives stale daily/session files and enforces retention windows. Leave on unless you want to manage cleanup yourself.

consolidation_extract_facts: bool

Also extract atomic durable facts from each consolidated turn and store them as individual Core memories. Default off; the flip is sequenced in a later phase. SQLite-only: enabling this requires the sqlite memory backend globally and on every agent (validated at config load).

archive_after_days: u32

Move daily/session files to the archive directory after this many days. Keeps the hot working set small without deleting history.

purge_after_days: u32

Delete archived files permanently after this many days. Set high if you need long-term history; set low for privacy / disk-space reasons.

conversation_retention_days: u32

Delete conversation rows older than this many days from the DB (sqlite backend only). Age is measured by updated_at (last write time). 0 = keep forever.

daily_retention_days: u32

Delete daily memory rows older than this many days from the DB. Age is measured by updated_at (last write time). 0 = keep forever.

core_retention_days: u32

Delete core memory rows older than this many days from the DB. Age is measured by created_at (first-write time). Neither recall nor ordinary rewrites refresh created_at under the current SQLite upsert, so core retention is an absolute age limit from first write. Set this to a generously large window for durable core memories, or keep 0 = keep forever.

embedding_provider: String

Source of embedding vectors for semantic search. none = keyword-only retrieval (no API calls, no vector cost); openai = OpenAI’s embedding API; custom:URL = any OpenAI-compatible embedding endpoint (LiteLLM, local gateway, etc.).

embedding_model: String

Embedding model identifier — must match a model your chosen embedding model_provider serves (e.g. text-embedding-3-small for OpenAI). Changing this invalidates existing embeddings: the change is detected at startup and stale vectors are cleared automatically; run zeroclaw memory reindex to re-embed (or set auto_reindex_on_identity_change).

embedding_dimensions: usize

Vector width produced by the embedding model — must match the model’s native dimension or vectors won’t store correctly. Look up the number on the model_provider’s model page.

auto_reindex_on_identity_change: bool

Automatically re-embed all memories in the background when a change of embedding provider/model/dimensions is detected at startup (after the stale vectors have been cleared). Costs one embedding API call per memory, so it’s off by default — leave it off for large stores and run zeroclaw memory reindex explicitly instead.

embedding_api_key: Option<String>

Optional API key for the embedding endpoint. When set, embedding calls use this key instead of inheriting one from the seed model provider — decoupling embeddings from the chat model. Use it when the chat model runs on a provider that carries no usable embedding credential (e.g. an OAuth-only provider) while embeddings keep hitting an openai/custom: endpoint with their own key. Leave unset to inherit the seed provider’s key (backward-compatible default).

vector_weight: f64

How heavily vector (semantic) similarity counts when search_mode = hybrid. Raise toward 1.0 to favor meaning-based matches; lower it to lean on keyword overlap instead.

keyword_weight: f64

How heavily BM25 (keyword) overlap counts when search_mode = hybrid. Raise toward 1.0 for exact-term matching; lower it when paraphrases should still score well.

search_mode: SearchMode

How memories are retrieved: bm25 = keyword-only (no embeddings, cheapest); embedding = vector similarity only (needs an embedding model_provider); hybrid = blended keyword + vector score using the weights above (most robust).

min_relevance_score: f64

Minimum hybrid score (0.0–1.0) for a memory to be included in context. Memories scoring below this threshold are dropped to prevent irrelevant context from bleeding into conversations. Default: 0.4

embedding_cache_size: usize

Max embedding cache entries before LRU eviction

chunk_max_tokens: usize

Max tokens per chunk for document splitting

response_cache_enabled: bool

Enable LLM response caching to avoid paying for duplicate prompts

response_cache_ttl_minutes: u32

TTL in minutes for cached responses (default: 60)

response_cache_max_entries: usize

Max number of cached responses before LRU eviction (default: 5000)

response_cache_hot_entries: usize

Max in-memory hot cache entries for the two-tier response cache (default: 256)

snapshot_enabled: bool

Enable periodic export of core memories to MEMORY_SNAPSHOT.md

snapshot_on_hygiene: bool

Run snapshot during hygiene passes (heartbeat-driven)

auto_hydrate: bool

Auto-hydrate from MEMORY_SNAPSHOT.md when brain.db is missing

retrieval_stages: Vec<String>

Retrieval stages for per-agent recall. Only "cache" is active: it enables an in-process, per-handle hot cache over recall results and is omitted from the default so recall stays coherent across handles. "fts" and "vector" are reserved for when the backend exposes distinct FTS and vector operations; recall is a single hybrid backend call today, so those names have no effect (kept for forward compat).

candidate_multiplier: usize

Candidate pool multiplier over the final recall limit before blend/rerank trimming. Values must be in 1..=20; runtime also enforces a bounded candidate pool.

rerank_enabled: bool

Enable the recall rerank stage: blend retrieval score with importance and recency, collapse near-duplicate entries, then trim back to the recall limit. The advanced strategy below runs when the candidate count reaches rerank_threshold.

rerank_threshold: usize

Minimum candidate count to trigger the advanced rerank strategy.

rerank_strategy: String

Advanced rerank strategy. Valid: “none”, “mmr”.

mmr_lambda: f64

MMR relevance-vs-diversity weight, where 1.0 means relevance-only.

importance_weight: f64

Importance weight used by the recall blend.

recency_weight: f64

Recency weight used by the recall blend.

fts_early_return_score: f64

Reserved (0.0-1.0): the FTS score above which recall would skip the vector stage. Inert until the backend exposes distinct FTS and vector operations; recall is a single hybrid call today, so this has no effect.

default_namespace: String

Default namespace for memory entries.

conflict_threshold: f64

Cosine similarity threshold for conflict detection (0.0–1.0).

conflict_supersede_enabled: bool

Enable reversible supersede soft-hide machinery when wired.

dedup_on_write: bool

Enable write-time near-duplicate detection.

dedup_jaccard_threshold: f64

Jaccard threshold for text-only duplicate detection.

dedup_action: MemoryDedupAction

Action to take when a duplicate is detected.

core_max_rows: u64

Maximum Core rows before budget compaction. 0 = unbounded.

core_max_bytes: u64

Maximum Core bytes before budget compaction. 0 = unbounded.

daily_max_rows: u64

Maximum Daily rows before budget compaction. 0 = unbounded.

evict_order: MemoryEvictOrder

Eviction ordering for budget compaction.

pin_namespaces: Vec<String>

Namespaces protected from budget eviction.

pin_min_importance: f64

Pin entries at or above this importance. >1.0 means disabled.

audit_enabled: bool

Enable audit logging of memory operations.

audit_retention_days: u32

Retention period for audit entries in days (default: 30).

policy: MemoryPolicyConfig

Memory policy configuration.

types: MemoryTypesConfig

Typed memory configuration ([memory.types] section).

Implementations

impl MemoryConfig

pub fn configurable_prefix() -> &'static str

Returns the #[prefix] value for this Configurable struct.

pub fn secret_fields(&self) -> Vec<SecretFieldInfo>

Returns metadata about all #[secret] fields on this struct and nested children.

pub fn secret_field_terminals() -> Vec<&'static str>

pub fn encrypt_secrets(&mut self, store: &SecretStore) -> Result<()>

Encrypt all secret fields in place using the provided store.

pub fn decrypt_secrets(&mut self, store: &SecretStore) -> Result<()>

Decrypt all secret fields in place using the provided store.

pub fn set_secret(&mut self, name: &str, value: String) -> Result<()>

Set a secret field by its full dotted name, dispatching to nested children.

pub fn prop_fields(&self) -> Vec<PropFieldInfo>

Returns metadata about all property fields on this struct and nested children.

pub fn get_prop(&self, name: &str) -> Result<String>

Get a property value by its full dotted name, returning it as a display string.

pub fn set_prop(&mut self, name: &str, value_str: &str) -> Result<()>

Set a property value by its full dotted name, parsing from string.

pub fn prop_is_secret(name: &str) -> bool

Check if a property name refers to a secret field (static, no instance needed).

pub fn init_defaults(&mut self, prefix: Option<&str>) -> Vec<&'static str>

Instantiate None nested sections whose prefix matches. Returns the prefixes that were initialized.

pub fn map_key_sections() -> Vec<MapKeySection>

Enumerate every map-keyed (HashMap<String, T>) and list-shaped (Vec<T>) section discoverable from this Configurable’s tree. The dashboard / CLI consume this to surface “+ Add” affordances without hardcoding the section list.

pub fn nested_section_help(name: &str) -> Option<&'static str>

Help blurb for a #[nested] field on this struct, sourced from the field-level /// docstring. Returns None for unknown names so callers can fall through to a different lookup.

pub fn nested_section_group(name: &str) -> Option<&'static str>

pub fn get_map_keys(&self, section_path: &str) -> Option<Vec<String>>

Return the current alias keys at section_path, or None if the path doesn’t resolve to a map-keyed section in this tree.

pub fn nested_option_entries(&self) -> Vec<NestedOptionEntry>

pub fn create_map_key( &mut self, section_path: &str, map_key: &str, ) -> Result<bool, String>

pub fn delete_map_key( &mut self, section_path: &str, map_key: &str, ) -> Result<bool, String>

pub fn rename_map_key( &mut self, section_path: &str, map_key: &str, new_key: &str, ) -> Result<bool, String>

Trait Implementations

impl Clone for MemoryConfig

fn clone(&self) -> MemoryConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for MemoryConfig

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

Formats the value using the given formatter.

impl Default for MemoryConfig

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for MemoryConfig

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl JsonSchema for MemoryConfig

fn schema_name() -> Cow<'static, str>

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn inline_schema() -> bool

Whether JSON Schemas generated for this type should be included directly in parent schemas, rather than being re-used where possible using the $ref keyword.

impl MaskSecrets for MemoryConfig

fn mask_secrets(&mut self)

fn restore_secrets_from(&mut self, current: &Self)

impl Serialize for MemoryConfig

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.