MemoryConfig

For the full field-by-field reference (including which fields are actually read at runtime vs. purely decorative), see Configuration. This page documents the class API itself.

Purpose

MemoryConfig is a single @dataclass holding every tunable in the package — memory-tier capacities, retrieval/importance thresholds, embedding settings, persistence paths, decay parameters, and a handful of per-memory-class defaults. It is validated on construction and can be built from environment variables.

Constructor

All 32 fields have defaults, so MemoryConfig() with no arguments is valid:

from zerda.memory import MemoryConfig

config = MemoryConfig()                          # all defaults
config = MemoryConfig(max_short_term=50, decay_rate=0.2)  # override specific fields

See Configuration → Full field reference for every field, its type, default, and — critically — whether it's actually consumed anywhere in this source tree.

__post_init__ / validation

Raises ValueError if any of:

if self.max_short_term < 1:
    raise ValueError("max_short_term must be at least 1")
if not 0 <= self.importance_threshold <= 1:
    raise ValueError("importance_threshold must be between 0 and 1")
if not 0 <= self.similarity_threshold <= 1:
    raise ValueError("similarity_threshold must be between 0 and 1")
if self.retrieval_limit < 1:
    raise ValueError("retrieval_limit must be at least 1")
if self.enable_decay and not 0 <= self.decay_rate <= 1:
    raise ValueError("decay_rate must be between 0 and 1")

Note decay_rate is only range-checked if enable_decay is True — setting enable_decay=False with an out-of-range decay_rate (e.g. 5.0) will not raise, since the field isn't actually gated by enable_decay anywhere else in the codebase (see Configuration).

from_env() -> MemoryConfig (classmethod)

config = MemoryConfig.from_env()

Reads exactly five environment variables (MEMORY_MAX_SHORT_TERM, MEMORY_MAX_LONG_TERM, MEMORY_EMBEDDING_MODEL, MEMORY_PERSISTENCE_PATH, MEMORY_ENABLE_PERSISTENCE); every other field takes its dataclass default. Note that MEMORY_MAX_SHORT_TERM's fallback here is 100, which differs from the dataclass field's own default of 1000 — if the env var is unset, from_env() still produces max_short_term=100, not 1000.

MEMORY_ENABLE_PERSISTENCE is parsed via .lower() == 'true' — any value other than a case-insensitive "true" (including "1", "yes", "") is treated as False.

to_dict() -> dict

Returns 10 of the 32 fields — see Configuration → Serializing configuration for the full list and a dataclasses.asdict() alternative if you need all fields.

Raises

Thread safety

MemoryConfig is an ordinary mutable dataclass with no locking. It's typically constructed once and treated as read-only thereafter, but nothing prevents concurrent mutation races if you share one instance across threads and modify fields after construction.

Examples

from zerda.memory import MemoryConfig

# 1. Basic
config = MemoryConfig()

# 2. Intermediate — override several fields
config = MemoryConfig(
    max_short_term=200,
    importance_threshold=0.6,
    persistence_path="/data/agent_memory",
)

# 3. From environment
import os
os.environ["MEMORY_MAX_LONG_TERM"] = "5000"
config = MemoryConfig.from_env()
print(config.max_long_term)  # 5000

# 4. Error handling
try:
    MemoryConfig(importance_threshold=1.5)
except ValueError as e:
    print(e)  # "importance_threshold must be between 0 and 1"

# 5. Production — full serialization for logging
from dataclasses import asdict
import json
print(json.dumps(asdict(config), indent=2))

Best practices

• Use dataclasses.asdict(config) rather than config.to_dict() if you need a complete snapshot — see Known Issues.
• Don't assume every field changes runtime behavior — cross-reference Configuration before relying on a field you haven't verified.

Common mistakes

• Assuming from_env() reads all 32 fields from environment variables — it reads only five.
• Setting enable_decay=False and expecting decay_rate to still be validated — it won't be.

Related APIs

• Configuration — full field reference.
• AIMemoryManager — primary consumer of MemoryConfig.
• MemoryType.default_capacity — reads MemoryConfig's class-level defaults, not your instance.