Skip to content

symfonic.capabilities.memory.provenance

provenance

What activation records about itself, so a surprising recall can be explained.

A memory that reached a prompt because the query matched it needs no explanation. A memory that reached it because it is two hops from something the user mentioned is the one a user asks "how did you know that?" about — and the one an operator has to be able to audit when the answer is "it should not have".

So this module holds the vocabulary, separate from the walk that produces it (:mod:.activation). The split is not bookkeeping: these types are read by event mapping, by the hydration record, and eventually by a consolidation pass deciding which inferred edges to make real, none of which want the traversal.

Provenance rides the record. :attr:~.records.MemoryRecord.origin is the field T3.3.1 reserved for it, and :func:activation_origin is the one place its format is decided, so "where did this come from?" is answered by the memory rather than by a side table that can drift from it.

ActivatedNode dataclass 

ActivatedNode(record_id: str, label: str, layer: MemoryLayer, score: float, hop: int = 0, source_id: str = '', relationship: str = '')

One memory the activation pass lit up, and how it got there.

of classmethod 

of(record: MemoryRecord, *, score: float, hop: int = 0, source_id: str = '', relationship: str = '') -> ActivatedNode

Build a node from the memory it stands for, with a bounded label.

Source code in src/symfonic/capabilities/memory/provenance.py 
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
@classmethod
def of(
    cls,
    record: MemoryRecord,
    *,
    score: float,
    hop: int = 0,
    source_id: str = "",
    relationship: str = "",
) -> ActivatedNode:
    """Build a node from the memory it stands for, with a bounded label."""
    label = flatten(record.text).strip()
    if len(label) > MAX_LABEL_CHARS:
        label = label[: MAX_LABEL_CHARS - 1].rstrip() + "…"
    return cls(
        record_id=record.record_id,
        label=label,
        layer=record.layer,
        score=score,
        hop=hop,
        source_id=source_id,
        relationship=relationship,
    )

ActivationEdge dataclass 

ActivationEdge(source_id: str, target_id: str, relationship: str = 'associated', weight: float = 1.0)

One traversal, kept so a later correction pass can see what was believed.

ActivationLog dataclass 

ActivationLog(nodes: tuple[ActivatedNode, ...] = (), edges: tuple[ActivationEdge, ...] = (), paths: tuple[tuple[str, ...], ...] = (), truncated: bool = False, degraded: bool = False)

The provenance of one activation pass.

Returned from the walk rather than stored on it, so two concurrent turns cannot read each other's expansion.

Association dataclass 

Association(source_id: str, target: MemoryRecord, relationship: str = 'associated', weight: float = 1.0)

One edge out of a memory, as a backend reports it.

activation_origin 

activation_origin(source_id: str, hop: int) -> str

The provenance stamped on a memory that activation reached.

Source code in src/symfonic/capabilities/memory/provenance.py 
47
48
49
def activation_origin(source_id: str, hop: int) -> str:
    """The provenance stamped on a memory that activation reached."""
    return f"activation:{source_id}:hop{hop}"