Semantic Memory Models
Structured models for semantic memory dedupe.
This module contains dedupe partition models, job settings, and run-result objects so the main job orchestration stays focused on control flow.
Some underscore-prefixed imports from semantic_memory_helpers are shared
package-internal utilities. They are intentionally reused by sibling modules
inside gllm_memory.dedupe and are not meant to be public package API.
SemanticMemoryDedupeDecision
Bases: BaseModel
One structured result for one processed dedupe decision.
group_memory_ids contains every memory row that participated in the
evaluated duplicate group. It is not a delete list. For destructive
outcomes, deleted_memory_ids is the authoritative field.
memory_ids
property
Return the backward-compatible alias for group_memory_ids.
Returns:
| Type | Description |
|---|---|
list[str]
|
list[str]: Participating memory identifiers for the dedupe group. |
normalize_group_memory_ids(data)
classmethod
Normalize legacy memory_ids input into group_memory_ids.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
Any
|
Raw model input. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Any |
Any
|
Normalized model input. |
SemanticMemoryDedupeRunResult(processed_targets=0, processed_groups=0, merged_groups=0, partial_groups=0, skipped_groups=0, skipped_important_groups=0, skipped_large_targets=0, skipped_rows_missing_partition_metadata=0, updated_memories=0, deleted_memories=0, decisions=list())
dataclass
Aggregate mutable counters for one dedupe run.
SemanticMemoryDedupeSettings
Bases: BaseModel
Environment-backed settings for the weekend dedupe job.
from_env(env=None)
classmethod
Build settings from environment variables.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
env
|
Mapping[str, str] | None
|
Optional environment map.
Defaults to |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
Self |
Self
|
Parsed settings object. |
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. |
should_run_at(current_time=None)
Check whether the job should run at the given server-local time.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
current_time
|
datetime | None
|
Time to evaluate. If the value is naive, it is interpreted as UTC. Defaults to the current server-local time. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
|
SemanticMemoryDedupeTarget
Bases: BaseModel
One explicit dedupe partition target.
The first dedupe phase works on one concrete memory partition at a time.
The partition key is:
scope + user_id + agent_id + source + target.
source and target default to the current scope mapping when they
are omitted by the caller.
metadata_filter()
Build the metadata filter for this target partition.
Returns:
| Type | Description |
|---|---|
dict[str, str]
|
dict[str, str]: Metadata filter with |
partition_key()
Return one readable partition key for logs.
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
Stable partition identifier string. |
populate_source_and_target(value)
classmethod
Populate source and target from the scope identity.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
Raw model input. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Any |
Any
|
Validated model payload. |
scopes()
Return the scope set expected by memory read and write APIs.
Returns:
| Type | Description |
|---|---|
set[MemoryScope]
|
set[MemoryScope]: Single-item scope set for this partition. |