Store Scanner

Internal scanner contract for semantic memory dedupe.

This module defines the minimal scan abstraction used by the semantic dedupe job. The scanner reads raw memory rows from the configured vector store without coupling the dedupe core to any specific memory provider client.

BaseSemanticMemoryStoreScanner

Bases: Protocol

Scan memory rows directly from the configured vector store.

Implementations must provide scan_page. Overriding count_partition_sizes is optional: the protocol default returns None to signal that the scanner does not expose a native count-only partition prepass, so the dedupe job should fall back to a full-store scan.

count_partition_sizes(*, lookback_since=None) async

Return one count-only partition-size map when supported.

Parameters:

Name	Type	Description	Default
lookback_since	datetime | None	Optional lower bound for created_at or updated_at. Defaults to None.	None

Returns:

Type	Description
dict[str, int] | None	dict[str, int] | None: Partition-size map keyed by build_semantic_partition_lookup_key(...), or None when the scanner does not support a native count prepass.

Notes

Implementations may omit this override and inherit the default None return value.

scan_page(*, page, page_size, lookback_since=None) async

Return one page of memory rows from the underlying vector store.

Parameters:

Name	Type	Description	Default
page	int	One-based page number.	required
page_size	int	Page size for this scan request.	required
lookback_since	datetime | None	Optional lower bound for created_at or updated_at. Defaults to None.	None

Returns:

Type	Description
list[Chunk]	list[Chunk]: Memory rows represented as chunks.

build_semantic_partition_lookup_key(*, role, source, target)

Build one stable lookup key for semantic dedupe partition counts.

Parameters:

Name	Type	Description	Default
role	str	Stored memory role.	required
source	str	Stored source identity.	required
target	str	Stored target identity.	required

Returns:

Name	Type	Description
str	str	Stable lookup key.