Q&A: Phase 18.2 — MemoryConsolidator

[web3guru888]

Q&A: Phase 18.2 — MemoryConsolidator

Community Q&A for the MemoryConsolidator component (issue #453). Ask questions below or review the pre-seeded pairs.

---

Q1: Why an async background loop vs synchronous consolidation?

A: Consolidation must never block the CognitiveCycle hot path. If _consolidate_trace() were called synchronously inside run_cycle(), a slow WorldModel.upsert_pattern() (e.g. a database write) would introduce latency into every cognitive tick. The background asyncio.Task runs independently — it yields with await asyncio.wait_for(stop_event, timeout=sweep_interval_s) between sweeps, so the event loop remains responsive.

Tuning sweep_interval_s: lower values (e.g. 5s) increase consolidation throughput at the cost of more CPU; higher values (e.g. 60s) reduce overhead but allow episodic backlog to grow. A reasonable default is 30s. Monitor consolidation_sweep_total rate to detect stalls.

---

Q2: How does HYBRID strategy balance the three scores?

A: HYBRID computes a weighted sum:

score = 0.3 * recency + 0.4 * frequency + 0.3 * surprise

Where:

• recency = 1 / (age_seconds + 1) — bounded in (0, 1], decays rapidly
• frequency = trace.frequency / max_freq — normalised to [0, 1] within the current candidate batch
• surprise = trace.surprise_score — already [0, 1] from SurpriseDetector

The weights sum to 1.0 (0.3 + 0.4 + 0.3). Frequency has the highest weight because repeated patterns have the strongest evidence for generalisation. Normalisation of frequency is per-sweep: max_freq = max(t.frequency for t in candidates). This means a trace with frequency=1 in a batch where the max is also 1 scores 1.0 for frequency — the strategy is relative within each sweep batch, not absolute.

---

Q3: What happens when WorldModel rejects a SemanticPattern?

A: world_model.upsert_pattern() raises WorldModelError on storage failure. The current design in _consolidate_trace() does not retry — it logs the error and continues with the next trace. Rationale: consolidation is a background best-effort process; a single rejection should not halt the entire sweep.

For production use cases where pattern durability is critical, a retry queue can be added: failed patterns are appended to _retry_queue: deque and re-attempted on the next sweep before fetching new candidates. This is a planned enhancement (Phase 18.5 TemporalCoherenceArbiter may address this).

---

Q4: How does SurpriseDetector integrate?

A: SurpriseDetector (Phase 13.4) annotates events with a surprise score at the point they are written to TemporalGraph. When an EpisodicTrace is created (grouping a set of event IDs), the trace's surprise_score is set to the max (or mean) surprise score across its constituent events.

MemoryConsolidator uses this score in two ways:

1. SURPRISE strategy: traces with surprise_score < surprise_threshold (default 0.7) score 0.0 and are excluded from consolidation — only genuinely surprising traces are promoted to WorldModel
2. HYBRID strategy: surprise contributes 0.3 * surprise_score to the blend — surprising traces are ranked higher but not exclusively selected

SurpriseDetector is passed to AsyncMemoryConsolidator.__init__() for potential future use (e.g. real-time re-scoring of candidate traces during sweep); the current implementation reads trace.surprise_score directly from the frozen dataclass.

---

Q5: What is the purpose of dry_run mode?

A: ConsolidatorConfig(dry_run=True) enables a non-mutating sweep:

• _consolidate_trace() computes features and scores but does not call world_model.upsert_pattern()
• _patterns dict is not updated
• prune_old_traces() is a no-op and returns 0

Use cases:

1. Pre-production profiling: measure sweep latency, candidate counts, and score distributions without touching production WorldModel
2. Unit testing: inject fakes for TemporalGraph and SurpriseDetector without needing a real WorldModel stub
3. Debug/inspection: run dry_run=True in production briefly to log what would be consolidated, then disable to execute

dry_run metrics can optionally emit with a dry_run="true" label to distinguish from live sweeps in Grafana.

---

Q6: How do we prevent memory bloat in TemporalGraph?

A: Two mechanisms:

1. prune_old_traces(retention_ns): removes traces where timestamp_ns < cutoff_ns. Called explicitly or via a scheduled task. ConsolidatorConfig.retention_days = 7.0 gives a cutoff_ns = time.monotonic_ns() - int(7 * 86400 * 1e9). Only consolidated traces should be pruned (the implementation checks trace.consolidated == True before deletion — unconsolidated traces are preserved regardless of age, unless an explicit override is passed).

2. Background loop with max_traces_per_sweep: by processing traces continuously in the background, the consolidation rate keeps pace with ingestion rate under normal load. If ingestion spikes, the sweep will catch up over subsequent intervals.

Monitor active_patterns_count as a proxy for WorldModel growth (should grow slowly and plateau); monitor TemporalGraph trace count separately to detect backlog accumulation.

---

Q7: Grafana — show consolidation rate and active patterns

A: Two recommended panels:

panels:
  - title: Consolidation Throughput
    type: timeseries
    gridPos:
      h: 8
      w: 12
    targets:
      - expr: rate(traces_consolidated_total[5m])
        legendFormat: traces/sec
      - expr: rate(consolidation_sweep_total[5m])
        legendFormat: sweeps/sec
    fieldConfig:
      defaults:
        unit: ops

  - title: Active Semantic Patterns
    type: stat
    gridPos:
      h: 4
      w: 6
    targets:
      - expr: active_patterns_count
        legendFormat: patterns
    fieldConfig:
      defaults:
        unit: short
        thresholds:
          steps:
            - color: green
              value: 0
            - color: yellow
              value: 500
            - color: red
              value: 2000

  - title: Sweep p95 Latency
    type: timeseries
    gridPos:
      h: 8
      w: 12
    targets:
      - expr: >
          histogram_quantile(0.95,
            rate(consolidation_sweep_duration_seconds_bucket[5m]))
        legendFormat: p95 sweep latency
    fieldConfig:
      defaults:
        unit: s

Alert rule example (consolidation stalled):

alert: ConsolidationSweepStalled
expr: rate(consolidation_sweep_total[10m]) == 0
for: 5m
labels:
  severity: warning
annotations:
  summary: "MemoryConsolidator background loop has stalled"
  description: "No consolidation sweeps in 10 minutes — check asyncio.Task health"