Memory Maintenance

Scheduled vector-memory maintenance domain.

MemoryMaintenanceJob(*, memory_client, scanner, mutation_coordinator=None)

Run retention and semantic dedupe as separate maintenance phases.

Initialize independent maintenance phases with shared infrastructure.

Parameters:

Name	Type	Description	Default
memory_client	BaseMemoryClient	Client used only by semantic dedupe.	required
scanner	BaseMemoryMaintenanceStoreScanner	Store scanner used by both independent maintenance phases.	required
mutation_coordinator	MemoryMaintenanceMutationCoordinator | None	Optional synchronization coordinator for successful maintenance mutations. Defaults to None.	None

run(*, similarity_threshold=DEFAULT_MEMORY_DEDUP_SIMILARITY_THRESHOLD, max_candidates_per_anchor=DEFAULT_MEMORY_DEDUP_MAX_CANDIDATES_PER_ANCHOR, max_target_memories=DEFAULT_MEMORY_DEDUP_MAX_TARGET_MEMORIES, lookback_days=DEFAULT_MEMORY_DEDUP_LOOKBACK_DAYS, retention_days=DEFAULT_MEMORY_RETENTION_DAYS, retention_enabled=False, dedupe_enabled=False, renew_lease=None) async

Run retention before the independent semantic-deduplication pass.

Parameters:

Name	Type	Description	Default
similarity_threshold	float	Dedupe similarity threshold. Defaults to 0.65.	DEFAULT_MEMORY_DEDUP_SIMILARITY_THRESHOLD
max_candidates_per_anchor	int	Dedupe candidate limit. Defaults to 100.	DEFAULT_MEMORY_DEDUP_MAX_CANDIDATES_PER_ANCHOR
max_target_memories	int	Dedupe partition safeguard. Defaults to 5000.	DEFAULT_MEMORY_DEDUP_MAX_TARGET_MEMORIES
lookback_days	int	Dedupe recent-window size. Defaults to 7.	DEFAULT_MEMORY_DEDUP_LOOKBACK_DAYS
retention_days	int	Retrieval retention period. Defaults to 90.	DEFAULT_MEMORY_RETENTION_DAYS
retention_enabled	bool	Whether to run retrieval retention. Defaults to False.	False
dedupe_enabled	bool	Whether to run semantic dedupe. Defaults to False.	False
renew_lease	Callable[[], Awaitable[bool]] | None	Optional distributed maintenance ownership callback. Defaults to None.	None

Returns:

Name	Type	Description
MemoryMaintenanceRunResult	MemoryMaintenanceRunResult	Results from both independent phases.

MemoryMaintenanceRunResult(retention, dedupe, retention_error=None, dedupe_error=None) dataclass

Results for one complete maintenance run.

has_failures property

Return whether one independent maintenance phase failed.

Returns:

Name	Type	Description
bool	bool	True when retention or dedupe recorded an error.

empty() classmethod

Build an empty result when another pod owns the maintenance lease.

Returns:

Name	Type	Description
MemoryMaintenanceRunResult	'MemoryMaintenanceRunResult'	Empty retention and dedupe results.

MemoryMaintenanceSettings

Bases: BaseModel

Environment-backed settings for scheduled vector-memory maintenance.

enabled property

Return whether at least one scheduled maintenance phase is enabled.

Returns:

Name	Type	Description
bool	bool	True when retention or semantic dedupe should run.

from_env(env=None) classmethod

Build maintenance settings from environment variables.

Parameters:

Name	Type	Description	Default
env	Mapping[str, str] | None	Optional environment map. Defaults to os.environ.	None

Returns:

Name	Type	Description
Self	Self	Parsed maintenance settings.

normalize_weekday()

Normalize the configured weekday alias.

Returns:

Name	Type	Description
Self	Self	Normalized settings object.

Raises:

Type	Description
ValueError	If the configured weekday is invalid.

scheduled_run_at(current_time)

Resolve the scheduled minute that is eligible for a catch-up run.

Parameters:

Name	Type	Description	Default
current_time	datetime	Current server-local time to evaluate.	required

Returns:

Type	Description
datetime | None	datetime | None: Scheduled local timestamp for the current day, or
datetime | None	None when the configured weekday has not yet reached its run time.

should_run_at(current_time=None)

Check whether maintenance should run at the current server-local minute.

Parameters:

Name	Type	Description	Default
current_time	datetime | None	Time to evaluate. Naive values are interpreted as UTC. Defaults to the current local time.	None

Returns:

Name	Type	Description
bool	bool	True when the configured schedule matches.