Skip to content

symfonic.memory.working

working

Working-memory summarisation primitives (v7.0 T09).

The canonical WorkingLayer lives under symfonic.memory.layers.working. This package holds the summarisers used when FrameworkConfig.stm_summary_mode is set to extractive or llm. Keeping them out of the layer module keeps the layer under the 300-line SOLID cap.

STMSummary dataclass 

STMSummary(
    text: str,
    mode_used: SummaryMode,
    entry_count: int,
    truncated: bool = False,
)

Result of an STM summary pass.

Attributes:

Name Type Description
text str

Rendered summary (may be empty when no source entries).
mode_used SummaryMode

Actual mode applied. When the requested mode was llm but the call failed, this is extractive — downstream telemetry can count fallbacks.
entry_count int

Number of source entries that fed the summary.
truncated bool

True when the deterministic path truncated to the configured token budget.

summarize_entries 

summarize_entries(
    entries: list[MemoryEntry],
    *,
    mode: SummaryMode,
    max_chars: int = 1000,
    model_provider: _ModelProviderLike | None = None,
    model_config: Any | None = None,
    observability_hook: Any | None = None,
    run_id: str = "",
) -> STMSummary

Summarise entries according to mode.

Parameters:

Name Type Description Default
entries list[MemoryEntry]

Dropped working-memory entries (FIFO evictees).

 required
mode SummaryMode

off / extractive / llm.

 required
max_chars int

Upper bound on the summary body. 0 disables truncation.

 1000
model_provider _ModelProviderLike | None

Required when mode == "llm". When absent the classifier silently downgrades to extractive.

 None
model_config Any | None

Passed verbatim to model_provider.get_chat_model.

 None
observability_hook Any | None

v8.3.2 (G3) -- when supplied AND mode == "llm", the summary LLM call emits on_llm_start/on_llm_end on the always-on ObservabilityHook so the (previously SILENT) STM summary tokens are visible on cortex/OTel spans. None resolves to a NoOpObservabilityHook -> byte-identical when unwired. NOTE: the only in-tree caller (WorkingLayer.summarize at working.py:206) invokes this in mode="extractive" and never threads a hook; the llm path is for direct callers.

 None
run_id str

Engine run identifier stamped on the hook events.

 ''

Returns:

Type Description
STMSummary

STMSummary. Never raises.
Source code in src/symfonic/memory/working/stm_summary.py 
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
def summarize_entries(
    entries: list[MemoryEntry],
    *,
    mode: SummaryMode,
    max_chars: int = 1000,
    model_provider: _ModelProviderLike | None = None,
    model_config: Any | None = None,
    observability_hook: Any | None = None,
    run_id: str = "",
) -> STMSummary:
    """Summarise ``entries`` according to ``mode``.

    Args:
        entries: Dropped working-memory entries (FIFO evictees).
        mode: ``off`` / ``extractive`` / ``llm``.
        max_chars: Upper bound on the summary body. ``0`` disables
            truncation.
        model_provider: Required when ``mode == "llm"``. When absent
            the classifier silently downgrades to ``extractive``.
        model_config: Passed verbatim to ``model_provider.get_chat_model``.
        observability_hook: v8.3.2 (G3) -- when supplied AND
            ``mode == "llm"``, the summary LLM call emits
            ``on_llm_start``/``on_llm_end`` on the always-on
            ``ObservabilityHook`` so the (previously SILENT) STM summary
            tokens are visible on cortex/OTel spans.  ``None`` resolves to
            a ``NoOpObservabilityHook`` -> byte-identical when unwired.
            NOTE: the only in-tree caller (``WorkingLayer.summarize`` at
            ``working.py:206``) invokes this in ``mode="extractive"`` and
            never threads a hook; the ``llm`` path is for direct callers.
        run_id: Engine run identifier stamped on the hook events.

    Returns:
        STMSummary. Never raises.
    """
    if mode == "off" or not entries:
        return STMSummary(text="", mode_used="off", entry_count=0)

    if mode == "llm" and model_provider is not None:
        try:
            text, truncated = _summarise_via_llm(
                entries, model_provider, model_config, max_chars,
                observability_hook=observability_hook,
                run_id=run_id,
            )
            return STMSummary(
                text=text,
                mode_used="llm",
                entry_count=len(entries),
                truncated=truncated,
            )
        except Exception:
            logger.warning(
                "LLM STM summary failed; falling back to extractive",
                exc_info=True,
            )

    text, truncated = _summarise_extractive(entries, max_chars=max_chars)
    return STMSummary(
        text=text,
        mode_used="extractive",
        entry_count=len(entries),
        truncated=truncated,
    )