Semantic Memory Strategy

Duplicate-candidate strategies for semantic memory dedupe.

This module isolates candidate discovery so the main dedupe job can stay focused on orchestration and the strategy surface stays open for later extensions such as LLM-judge flows.

BaseSemanticMemoryDedupeStrategy

Bases: ABC

Small extension contract for duplicate-candidate resolution.

find_duplicate_candidates(*, client, target, anchor, threshold, top_k) abstractmethod async

Find semantic duplicate candidates for one anchor row.

Parameters:

Name	Type	Description	Default
client	BaseMemoryClient	Memory client used for semantic search.	required
target	SemanticMemoryDedupeTarget	Active dedupe partition.	required
anchor	Chunk	Anchor memory row.	required
threshold	float	Similarity threshold.	required
top_k	int	Maximum number of results to request.	required

Returns:

Type	Description
list[Chunk]	list[Chunk]: Candidate rows returned by the current strategy.

EmbeddingSemanticMemoryDedupeStrategy

Bases: BaseSemanticMemoryDedupeStrategy

Embedding-only duplicate-candidate strategy.

This first phase uses normal semantic search with include_important=False. Because of that, the configured similarity threshold controls which important memories can enter the duplicate group. The later canonical rule important > newer > richer > older still applies inside the group, and important memories are still excluded from delete targets, but this phase does not force every important memory to be considered regardless of threshold. See semantic_memory_helpers._select_canonical_memory for the canonical selection rule.

find_duplicate_candidates(*, client, target, anchor, threshold, top_k) async

Search the current partition using the anchor content.

This method intentionally keeps include_important=False in the first implementation. That keeps the dedupe candidate set aligned with normal thresholded semantic matches and avoids expanding every anchor search with protected rows. The tradeoff is that the protection rule for important memories starts only after an important row is returned as a semantic candidate.

Parameters:

Name	Type	Description	Default
client	BaseMemoryClient	Memory client used for semantic search.	required
target	SemanticMemoryDedupeTarget	Active dedupe partition.	required
anchor	Chunk	Anchor memory row.	required
threshold	float	Similarity threshold.	required
top_k	int	Maximum number of results to request.	required

Returns:

Type	Description
list[Chunk]	list[Chunk]: Candidate rows that passed the semantic threshold.