Skip to content

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.

perf(memory/hnsw): pick eviction victims with heapq.nsmallest, not a full sort (#3167)

Abhay Singhb17b81279072
diff --git a/headroom/memory/adapters/hnsw.py b/headroom/memory/adapters/hnsw.py
index 5f474bd5c..48e087c64 100644
--- a/headroom/memory/adapters/hnsw.py
+++ b/headroom/memory/adapters/hnsw.py
@@ -13,6 +13,7 @@ Or via headroom extras:
from __future__ import annotations
+import heapq
import json
from dataclasses import dataclass
from datetime import datetime
@@ -393,15 +394,19 @@ class HNSWVectorIndex:
if not self._metadata:
return 0
- # Sort entries by importance (ascending), then by created_at (oldest first)
- sorted_entries = sorted(
+ # Select the `count` lowest-importance (then oldest) entries. nsmallest
+ # is O(n log count); fully sorting all entries just to take the first
+ # `count` was O(n log n), and eviction runs on every insert once a
+ # bounded index is at capacity. The selection is identical.
+ lowest_entries = heapq.nsmallest(
+ count,
self._metadata.items(),
key=lambda x: (x[1].importance, x[1].created_at),
)
# Evict the lowest importance entries
evicted = 0
- for memory_id, _metadata in sorted_entries[:count]:
+ for memory_id, _metadata in lowest_entries:
if memory_id not in self._memory_to_hnsw:
continue
diff --git a/tests/test_hnsw_only.py b/tests/test_hnsw_only.py
index 4c5c60df2..61b2cae82 100644
--- a/tests/test_hnsw_only.py
+++ b/tests/test_hnsw_only.py
@@ -276,3 +276,58 @@ class TestHNSWVectorIndex:
assert index2._max_entries == 50
assert index2._eviction_batch_size == 10
assert index2.size == 5
+
+
+class _StubHnswIndex:
+ """Minimal stand-in for the hnswlib index used by _evict_entries."""
+
+ def __init__(self) -> None:
+ self.deleted: list[int] = []
+
+ def mark_deleted(self, hnsw_id: int) -> None:
+ self.deleted.append(hnsw_id)
+
+
+def test_evict_entries_selects_lowest_importance_then_oldest() -> None:
+ """_evict_entries must remove the `count` lowest-importance (then oldest)
+ entries. This drives the selection logic directly (no hnswlib), locking in
+ the contract preserved when the full sort was replaced with heapq.nsmallest.
+ """
+ import types
+ from dataclasses import dataclass
+
+ from headroom.memory.adapters.hnsw import HNSWVectorIndex
+
+ @dataclass
+ class _Meta:
+ importance: float
+ created_at: float
+
+ # ids a..f: importance ascending; two ties (0.5) broken by created_at.
+ meta = {
+ "a": _Meta(0.1, 100.0),
+ "b": _Meta(0.2, 100.0),
+ "c": _Meta(0.5, 100.0), # older of the 0.5 tie
+ "d": _Meta(0.5, 200.0), # newer of the 0.5 tie
+ "e": _Meta(0.9, 100.0),
+ "f": _Meta(0.95, 100.0),
+ }
+ self = types.SimpleNamespace(
+ _metadata=dict(meta),
+ _memory_to_hnsw={k: i for i, k in enumerate(meta)},
+ _hnsw_to_memory=dict(enumerate(meta)),
+ _embeddings=dict.fromkeys(meta),
+ _index=_StubHnswIndex(),
+ _eviction_count=0,
+ )
+
+ evicted = HNSWVectorIndex._evict_entries(self, 3)
+
+ assert evicted == 3
+ # The three lowest by (importance, created_at): a, b, then c (older tie).
+ assert set(meta) - set(self._metadata) == {"a", "b", "c"}
+ assert "d" in self._metadata # newer of the 0.5 tie survives
+ # Mappings and embeddings for evicted ids are cleaned up too.
+ assert "a" not in self._memory_to_hnsw
+ assert "a" not in self._embeddings
+ assert self._eviction_count == 3