Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
feat(memory): persist TrafficLearner pending evidence across restarts + expose learner stats (#3104)
gglucass4257ed4df377
diff --git a/headroom/memory/traffic_learner.py b/headroom/memory/traffic_learner.pyindex e3ed50ba6..678fecf5b 100644--- a/headroom/memory/traffic_learner.py+++ b/headroom/memory/traffic_learner.py@@ -540,6 +540,10 @@ class TrafficLearner:# Hydrate persisted dedup state before workers spin up so cross-session# re-sightings bump existing rows instead of creating duplicates.await self._hydrate_persisted_state()+ # Rehydrate sub-threshold evidence from the previous process. Without+ # this every restart zeroed pending counts, so users with short or+ # restart-heavy sessions could never cross min_evidence.+ await self._load_pending_state()if self._save_task is None or self._save_task.done():self._save_task = asyncio.create_task(self._save_worker())if self._flush_task is None or self._flush_task.done():@@ -584,6 +588,9 @@ class TrafficLearner:except Exception:break+ # Snapshot sub-threshold evidence so it survives the restart.+ await self._save_pending_state()+# Final flush on shutdown — bypass debounce.await self.flush_to_file()@@ -601,6 +608,9 @@ class TrafficLearner:self._flush_dirty = Falseself._last_flush_at = time.monotonic()await self.flush_to_file()+ # Same debounce cycle also snapshots pending evidence, so a+ # crash (vs clean stop) loses at most one debounce window.+ await self._save_pending_state()except asyncio.CancelledError:breakexcept Exception as e:@@ -846,6 +856,7 @@ class TrafficLearner:"patterns_extracted": self._patterns_extracted,"patterns_saved": self._patterns_saved,"pending_patterns": len(self._pattern_counts),+ "min_evidence": self._min_evidence,"history_size": len(self._tool_history),}@@ -1415,6 +1426,82 @@ class TrafficLearner:# last-wins — we only need one id to target the bump.self._persisted_ids[h] = memory_id+ def _pending_state_path(self) -> Path | None:+ """Sidecar JSON next to memory.db holding sub-threshold evidence."""+ db_path = _resolve_backend_db_path(self._backend)+ if db_path is None:+ return None+ return db_path.with_name("pending_patterns.json")++ async def _save_pending_state(self) -> None:+ """Snapshot the pending accumulator so evidence survives restarts.++ Best-effort: failures are logged at debug and never propagate — the+ accumulator degrades gracefully back to per-process behavior.+ """+ path = self._pending_state_path()+ if path is None:+ return+ entries = [+ {+ "category": pattern.category.value,+ "content": pattern.content,+ "importance": pattern.importance,+ "count": count,+ "entity_refs": pattern.entity_refs,+ "metadata": pattern.metadata,+ "content_hash": h,+ }+ for h, (pattern, count) in self._pattern_counts.items()+ ]++ def _write() -> None:+ # tmp + rename so a crash mid-write can't truncate the file.+ tmp = path.with_name(path.name + ".tmp")+ tmp.write_text(json.dumps({"version": 1, "patterns": entries}))+ os.replace(tmp, path)++ try:+ await asyncio.to_thread(_write)+ except Exception as e:+ logger.debug("Traffic learner pending-state save failed: %s", e)++ async def _load_pending_state(self) -> None:+ """Rehydrate sub-threshold evidence saved by a previous process.++ Runs after _hydrate_persisted_state so entries whose pattern crossed+ the threshold in the meantime (hash now in _saved_hashes) are skipped;+ their re-sightings bump the persisted row instead. Unreadable or+ malformed files are ignored — the next snapshot overwrites them.+ """+ path = self._pending_state_path()+ if path is None or not path.exists():+ return+ try:+ data = json.loads(await asyncio.to_thread(path.read_text))+ except Exception as e:+ logger.debug("Traffic learner pending-state load failed: %s", e)+ return+ entries = data.get("patterns") if isinstance(data, dict) else None+ if not isinstance(entries, list):+ return+ for entry in entries[: self._max_pending_patterns]:+ try:+ h = entry["content_hash"]+ if not h or h in self._saved_hashes or h in self._pattern_counts:+ continue+ pattern = ExtractedPattern(+ category=PatternCategory(entry["category"]),+ content=entry["content"],+ importance=float(entry.get("importance", 0.5)),+ entity_refs=list(entry.get("entity_refs", [])),+ metadata=dict(entry.get("metadata", {})),+ content_hash=h,+ )+ self._pattern_counts[h] = (pattern, max(1, int(entry.get("count", 1))))+ except Exception:+ continue+async def _bump_persisted_evidence(self, memory_id: str) -> None:"""Atomically increment a persisted row's metadata.evidence_count."""db_path = _resolve_backend_db_path(self._backend)diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 19ca411db..9c49fa66d 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -4985,6 +4985,13 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:),},"toin": get_toin().get_stats(),+ # Auto-learning progress. `pending_patterns` counts sub-threshold+ # evidence so dashboards can show the learner is alive before the+ # first pattern crosses `min_evidence` (users otherwise read the+ # silence as "learning is broken").+ "traffic_learner": (+ proxy.traffic_learner.get_stats() if proxy.traffic_learner else None+ ),"proxy_inbound": proxy.metrics.inbound_snapshot(),"cache": await proxy.cache.stats() if proxy.cache else None,"rate_limiter": await proxy.rate_limiter.stats() if proxy.rate_limiter else None,diff --git a/tests/test_memory/test_traffic_learner.py b/tests/test_memory/test_traffic_learner.pyindex a3ed9052c..33186be3a 100644--- a/tests/test_memory/test_traffic_learner.py+++ b/tests/test_memory/test_traffic_learner.py@@ -2604,3 +2604,97 @@ class TestExtractPreferencesSentenceBoundary:assert not out[0].content.endswith(".")assert not out[0].content.endswith("!")assert not out[0].content.endswith("?")+++# =============================================================================+# Pending-state persistence across restarts+# =============================================================================+++class TestPendingStatePersistence:+ """Sub-threshold evidence must survive process restarts (sidecar JSON)."""++ _PATTERN_KWARGS = {+ "category": PatternCategory.ENVIRONMENT,+ "content": "Use /usr/bin/python3 for system scripts.",+ "importance": 0.6,+ }++ @pytest.mark.asyncio+ async def test_pending_evidence_survives_restart(self, tmp_path):+ """2 sightings before restart + 1 after = saved with evidence_count 3."""+ db = tmp_path / "memory.db"+ _init_db(db)++ first = TrafficLearner(backend=_FakeBackend(db), min_evidence=3)+ await first.start()+ for _ in range(2):+ await first._accumulate(ExtractedPattern(**self._PATTERN_KWARGS))+ await first.stop()++ sidecar = tmp_path / "pending_patterns.json"+ assert sidecar.exists()+ assert _read_traffic_rows(db) == [] # still below threshold++ second = TrafficLearner(backend=_FakeBackend(db), min_evidence=3)+ await second.start()+ assert second.get_stats()["pending_patterns"] == 1+ await second._accumulate(ExtractedPattern(**self._PATTERN_KWARGS))+ await _wait_for_saved(second, 1, db)+ await second.stop()++ rows = _read_traffic_rows(db)+ assert len(rows) == 1+ assert rows[0][2]["evidence_count"] == 3++ @pytest.mark.asyncio+ async def test_corrupt_pending_file_is_ignored(self, tmp_path):+ db = tmp_path / "memory.db"+ _init_db(db)+ (tmp_path / "pending_patterns.json").write_text("{not json")++ learner = TrafficLearner(backend=_FakeBackend(db), min_evidence=3)+ await learner.start() # must not raise+ assert learner.get_stats()["pending_patterns"] == 0+ await learner.stop()++ @pytest.mark.asyncio+ async def test_already_saved_pattern_not_rehydrated_as_pending(self, tmp_path):+ """A sidecar entry whose hash is already persisted is skipped on load."""+ import json as _json++ db = tmp_path / "memory.db"+ _init_db(db)++ first = TrafficLearner(backend=_FakeBackend(db), min_evidence=3)+ await first.start()+ for _ in range(3):+ await first._accumulate(ExtractedPattern(**self._PATTERN_KWARGS))+ await _wait_for_saved(first, 1, db)+ await first.stop()++ # Handcraft a stale sidecar claiming the saved pattern is still pending.+ h = ExtractedPattern(**self._PATTERN_KWARGS).content_hash+ (tmp_path / "pending_patterns.json").write_text(+ _json.dumps(+ {+ "version": 1,+ "patterns": [+ {+ "category": "environment",+ "content": self._PATTERN_KWARGS["content"],+ "importance": 0.6,+ "count": 2,+ "entity_refs": [],+ "metadata": {},+ "content_hash": h,+ }+ ],+ }+ )+ )++ second = TrafficLearner(backend=_FakeBackend(db), min_evidence=3)+ await second.start()+ assert second.get_stats()["pending_patterns"] == 0+ await second.stop()