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.

fix(memory): replace the HNSW vector when a memory is re-indexed (#4649)

HetCreepee638f9532b3
diff --git a/headroom/memory/adapters/hnsw.py b/headroom/memory/adapters/hnsw.py
index a8c03d2f4..5f9351ab4 100644
--- a/headroom/memory/adapters/hnsw.py
+++ b/headroom/memory/adapters/hnsw.py
@@ -494,11 +494,19 @@ class HNSWVectorIndex:
self._metadata[memory.id] = IndexedMemoryMetadata.from_memory(memory)
self._embeddings[memory.id] = embedding.copy()
- # Handle updates (hnswlib doesn't support true updates, so we track separately)
+ # Updates: add_items with an existing label replaces its vector. A batch
+ # can name the same id more than once; keep only the last entry so the
+ # graph, the cached embedding and the metadata end on the same vector
+ # (hnswlib may apply rows for one label out of order across threads).
+ update_memories = list({m.id: (m, emb) for m, emb in update_memories}.values())
+ if update_memories:
+ self._index.add_items(
+ np.vstack([emb for _, emb in update_memories]).astype(np.float32),
+ np.array([self._memory_to_hnsw[m.id] for m, _ in update_memories]),
+ )
for memory, embedding in update_memories:
self._metadata[memory.id] = IndexedMemoryMetadata.from_memory(memory)
self._embeddings[memory.id] = embedding.copy()
- # Note: HNSW embedding stays unchanged unless we remove and re-add
if self._auto_save and self._save_path:
self.save_index(self._save_path)
@@ -748,9 +756,7 @@ class HNSWVectorIndex:
async def update_embedding(self, memory_id: str, embedding: np.ndarray) -> bool:
"""Update the embedding for an indexed memory.
- Note: hnswlib doesn't support in-place updates. This stores the new
- embedding but the HNSW graph uses the original. For full update,
- remove and re-index the memory.
+ The new vector replaces the old one in the HNSW graph, so search uses it.
Args:
memory_id: The unique identifier of the memory.
@@ -777,15 +783,15 @@ class HNSWVectorIndex:
async def _update_embedding_internal(self, memory_id: str, embedding: np.ndarray) -> bool:
"""Internal embedding update without lock (caller must hold lock).
- hnswlib doesn't support true in-place updates, so we:
- 1. Store the new embedding in our local cache
- 2. The HNSW index continues to use the old embedding for search
-
- For a true update, the caller should remove and re-index.
+ hnswlib's ``add_items`` with an existing label replaces that element's
+ vector in place (``addPoint`` -> ``updatePoint``), so the label and the
+ id mappings stay as they are and search sees the new vector.
"""
- if memory_id not in self._memory_to_hnsw:
+ hnsw_id = self._memory_to_hnsw.get(memory_id)
+ if hnsw_id is None:
return False
+ self._index.add_items(embedding.reshape(1, -1), np.array([hnsw_id]))
self._embeddings[memory_id] = embedding.copy()
return True
diff --git a/tests/test_memory/test_hnsw_update_replaces_vector.py b/tests/test_memory/test_hnsw_update_replaces_vector.py
new file mode 100644
index 000000000..fed679463
--- /dev/null
+++ b/tests/test_memory/test_hnsw_update_replaces_vector.py
@@ -0,0 +1,107 @@
+"""Re-indexing a memory on the HNSW backend must move it to its new vector.
+
+`HierarchicalMemory.update`, `refresh` and `detach` re-index a memory under the
+same id after its content (and so its embedding) changed. The HNSW adapter only
+cached the new embedding; the graph kept the old vector, so search still found
+the memory by its OLD content and not by the new one.
+See https://github.com/headroomlabs-ai/headroom/issues/4362 (item 5).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from headroom.memory.models import Memory
+from headroom.memory.ports import VectorFilter
+
+try:
+ from headroom.memory.adapters.hnsw import _check_hnswlib_available
+
+ HNSW_AVAILABLE = _check_hnswlib_available()
+except ImportError:
+ HNSW_AVAILABLE = False
+
+pytestmark = [
+ pytest.mark.skipif(not HNSW_AVAILABLE, reason="hnswlib not installed"),
+ pytest.mark.asyncio,
+]
+
+DIM = 8
+OLD = np.eye(DIM, dtype=np.float32)[0]
+NEW = np.eye(DIM, dtype=np.float32)[1]
+
+
+def _index():
+ from headroom.memory.adapters.hnsw import HNSWVectorIndex
+
+ return HNSWVectorIndex(dimension=DIM, max_elements=16)
+
+
+async def _top(index, vector: np.ndarray) -> tuple[str, float]:
+ results = await index.search(VectorFilter(query_vector=vector, top_k=1))
+ return results[0].memory.id, results[0].similarity
+
+
+async def _seed(index) -> Memory:
+ memory = Memory(id="m1", content="old", user_id="u", embedding=OLD.copy())
+ await index.index(memory)
+ # A second memory so a stale vector cannot win by being the only entry.
+ await index.index(
+ Memory(id="m2", content="other", user_id="u", embedding=np.ones(DIM, np.float32))
+ )
+ return memory
+
+
+async def test_index_on_existing_id_replaces_the_vector() -> None:
+ index = _index()
+ memory = await _seed(index)
+
+ memory.embedding = NEW.copy()
+ await index.index(memory)
+
+ assert index.size == 2
+ found, similarity = await _top(index, NEW)
+ assert found == "m1"
+ assert similarity == pytest.approx(1.0, abs=1e-5)
+
+
+async def test_update_embedding_replaces_the_vector() -> None:
+ index = _index()
+ await _seed(index)
+
+ assert await index.update_embedding("m1", NEW.copy()) is True
+
+ found, similarity = await _top(index, NEW)
+ assert found == "m1"
+ assert similarity == pytest.approx(1.0, abs=1e-5)
+
+
+async def test_index_batch_on_existing_id_replaces_the_vector() -> None:
+ index = _index()
+ memory = await _seed(index)
+
+ memory.embedding = NEW.copy()
+ assert await index.index_batch([memory]) == 1
+
+ assert index.size == 2
+ found, similarity = await _top(index, NEW)
+ assert found == "m1"
+ assert similarity == pytest.approx(1.0, abs=1e-5)
+
+
+async def test_index_batch_repeated_id_ends_on_the_last_vector() -> None:
+ index = _index()
+ await _seed(index)
+
+ first = Memory(
+ id="m1", content="first", user_id="u", embedding=np.eye(DIM, dtype=np.float32)[2]
+ )
+ last = Memory(id="m1", content="last", user_id="u", embedding=NEW.copy())
+ await index.index_batch([first, last])
+
+ assert index.size == 2
+ found, similarity = await _top(index, NEW)
+ assert found == "m1"
+ assert similarity == pytest.approx(1.0, abs=1e-5)
+ assert np.array_equal(index._embeddings["m1"], NEW)