Update version to 0.2.0 and enhance README.md with new features

- Bump version in pyproject.toml and __init__.py to 0.2.0.
- Update README.md to reflect the addition of vector indexing in `create_memory` and improved search functionality with volatility re-ranking.
- Introduce new tests for vector index functionality in CI workflow.
- Enhance MemoryLayer to support vector index integration for improved memory retrieval performance.

Author: Rouche01

.github/workflows/ci.yml

@@ -28,6 +28,9 @@ jobs:
       - name: Run client tests
         run: python tests/test_client.py
 
+      - name: Run vector index tests
+        run: python tests/test_vector_index.py
+
       - name: Contradiction demo smoke test
         run: python examples/contradiction_demo.py
 

README.md

@@ -72,15 +72,27 @@ system = f"What you know about this user:\n{context}"
 
 | Method | Description |
 |---|---|
-| `create_memory(db, user_id)` | Factory with auto-detected embeddings |
+| `create_memory(db, user_id)` | Factory with auto-detected embeddings + vector index |
 | `Memory.add(text \| messages)` | Store a fact; slot-aware linking updates related memories |
-| `Memory.search(query, limit=5)` | Ranked memories (relevance + freshness) |
+| `Memory.search(query, limit=5)` | ANN candidates + volatility re-rank (relevance + freshness) |
 | `Memory.get_all()` | All active memories for this user |
 | `Memory.delete(id)` | Remove one memory |
 | `Memory.clear()` | Wipe user namespace |
 
 Advanced: `mem.layer` exposes `MemoryLayer` for low-level `observe()` / `write()`.
 
+`create_memory(..., vector_index="auto")` enables a SQLite embedding index when an
+embedder is present (`"off"` restores full-scan retrieval). VoltMem always applies
+volatility re-ranking on top of vector candidates — not raw ANN results.
+
+```mermaid
+flowchart LR
+  Q[search query] --> E[embed query]
+  E --> V[vector index: top candidates]
+  V --> S[SQLite: load memory records]
+  S --> R[volatility re-rank → current truth]
+```
+
 ---
 
 ## Why VoltMem

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "voltmem"
-version = "0.1.0"
+version = "0.2.0"
 description = "Current-truth memory for LLM agents — protect stable facts, update volatile ones."
 readme = "README.md"
 license = "MIT"

tests/test_vector_index.py

@@ -0,0 +1,156 @@
+"""
+Tests for vector index backends and MemoryLayer ANN retrieval.
+"""
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from voltmem import MemoryLayer
+from voltmem.embeddings import _cosine
+from voltmem.vector_index import BruteForceVectorIndex, SqliteVectorIndex, cosine_similarity
+
+
+# ── deterministic toy embedder for parity tests ───────────────────────────────
+
+_KEYWORDS = ("berlin", "paris", "concise", "stressed", "billing", "auth")
+
+
+def _toy_embed(text: str) -> list[float]:
+    t = text.lower()
+    vec = [1.0 if kw in t else 0.0 for kw in _KEYWORDS]
+    return vec if any(vec) else [0.1] * len(_KEYWORDS)
+
+
+def _toy_similarity(a: str, b: str) -> float:
+    return max(0.0, _cosine(_toy_embed(a), _toy_embed(b)))
+
+
+def _layer_with_index(mode: str = "brute"):
+    return MemoryLayer(
+        ":memory:",
+        similarity_fn=_toy_similarity,
+        embed_fn=_toy_embed,
+        vector_index=mode,
+        namespace="test",
+    )
+
+
+# ── index unit tests ──────────────────────────────────────────────────────────
+
+def test_brute_force_search_orders_by_similarity():
+    idx = BruteForceVectorIndex()
+    q = [1.0, 0.0, 0.0]
+    idx.upsert("a", "u1", "location", [1.0, 0.0, 0.0])
+    idx.upsert("b", "u1", "location", [0.8, 0.2, 0.0])
+    idx.upsert("c", "u1", "location", [0.0, 1.0, 0.0])
+    hits = idx.search(q, "u1", top_k=2)
+    assert [h[0] for h in hits] == ["a", "b"]
+
+
+def test_sqlite_index_namespace_isolation():
+    idx = SqliteVectorIndex(":memory:")
+    idx.upsert("a", "alice", "location", [1.0, 0.0])
+    idx.upsert("b", "bob", "location", [0.0, 1.0])
+    alice = idx.search([1.0, 0.0], "alice", top_k=5)
+    bob = idx.search([1.0, 0.0], "bob", top_k=5)
+    assert alice[0][0] == "a"
+    assert bob[0][0] == "b"
+    idx.close()
+
+
+def test_cosine_similarity_clamps_negative():
+    assert cosine_similarity([1.0, 0.0], [-1.0, 0.0]) == 0.0
+
+
+# ── MemoryLayer integration ───────────────────────────────────────────────────
+
+def test_retrieve_with_brute_index_matches_full_scan():
+    with _layer_with_index("brute") as mem:
+        mem.write("User lives in Berlin", domain="location")
+        mem.write("User prefers concise answers", domain="core_preference")
+        mem.write("User is stressed this week", domain="emotional_context")
+
+        indexed = mem.retrieve("concise communication", top_k=2)
+        mem._vector_index = None
+        full = mem.retrieve("concise communication", top_k=2)
+
+        assert [i.content for i in indexed.items] == [i.content for i in full.items]
+
+
+def test_retrieve_with_sqlite_index_matches_full_scan():
+    with _layer_with_index("sqlite") as mem:
+        mem.write("User lives in Berlin", domain="location")
+        mem.write("User lives in Paris now", domain="location")
+        mem.write("building the billing service", domain="current_project")
+
+        indexed = mem.retrieve("where does user live", top_k=1)
+        mem._vector_index = None
+        full = mem.retrieve("where does user live", top_k=1)
+
+        assert indexed.items[0].content == full.items[0].content
+
+
+def test_supersede_removes_old_vector():
+    with _layer_with_index("brute") as mem:
+        mem.write("User lives in Berlin", domain="location")
+        mem.observe(
+            "User lives in Paris now",
+            domain="location",
+            mismatch_magnitude=0.9,
+            source="explicit_statement",
+        )
+        active = mem._active(domain="location")
+        assert len(active) == 1
+        assert "Paris" in active[0].content
+        hits = mem._vector_index.search(_toy_embed("Berlin"), "test", top_k=5)
+        for item_id, _ in hits:
+            item = mem._store.get(item_id)
+            assert item is None or "Berlin" not in item.content
+
+
+def test_remove_and_clear_drop_vectors():
+    with _layer_with_index("sqlite") as mem:
+        r = mem.write("User lives in Berlin", domain="location")
+        mem.remove(r.item.id)
+        hits = mem._vector_index.search(_toy_embed("Berlin"), "test", top_k=5)
+        assert hits == []
+
+        mem.write("User lives in Paris", domain="location")
+        mem.clear()
+        hits = mem._vector_index.search(_toy_embed("Paris"), "test", top_k=5)
+        assert hits == []
+
+
+def test_vector_index_off_preserves_behavior():
+    with MemoryLayer(":memory:", vector_index="off") as mem:
+        mem.remember("I live in Berlin")
+        res = mem.remember("I live in Paris")
+        assert res.action in ("audited", "logged_mismatch")
+        assert len(mem._active(domain="location")) == 1
+
+
+if __name__ == "__main__":
+    tests = [
+        test_brute_force_search_orders_by_similarity,
+        test_sqlite_index_namespace_isolation,
+        test_cosine_similarity_clamps_negative,
+        test_retrieve_with_brute_index_matches_full_scan,
+        test_retrieve_with_sqlite_index_matches_full_scan,
+        test_supersede_removes_old_vector,
+        test_remove_and_clear_drop_vectors,
+        test_vector_index_off_preserves_behavior,
+    ]
+    passed = failed = 0
+    for t in tests:
+        try:
+            t()
+            print(f"  PASS  {t.__name__}")
+            passed += 1
+        except Exception as e:
+            print(f"  FAIL  {t.__name__}: {e}")
+            failed += 1
+    print(f"\n{passed}/{passed + failed} tests passed")
+    if failed:
+        sys.exit(1)

voltmem/__init__.py

@@ -36,6 +36,12 @@
 from .memory import MemoryLayer, WriteResult, RetrieveResult
 from .client import Memory, create_memory
 from .domains import MemoryItem, DOMAIN_VOLATILITY, SOURCE_RELIABILITY
+from .vector_index import (
+    VectorIndex,
+    BruteForceVectorIndex,
+    SqliteVectorIndex,
+    create_vector_index,
+)
 from .embeddings import EmbeddingSimilarity
 from .extract import HeuristicExtractor, LLMExtractor, HeuristicFactExtractor, LLMFactExtractor
 from .scoring import (
@@ -55,6 +61,10 @@
     "DOMAIN_VOLATILITY",
     "SOURCE_RELIABILITY",
     "EmbeddingSimilarity",
+    "VectorIndex",
+    "BruteForceVectorIndex",
+    "SqliteVectorIndex",
+    "create_vector_index",
     "HeuristicExtractor",
     "LLMExtractor",
     "HeuristicFactExtractor",
@@ -65,4 +75,4 @@
     "protection_weight",
 ]
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

voltmem/client.py

@@ -23,6 +23,7 @@ def create_memory(
     verbose: bool = False,
     llm_extract: bool = False,
     llm_domain: bool = False,
+    vector_index: str = "auto",
     **kwargs: Any,
 ) -> "Memory":
     """Create a production-ready memory instance with sensible defaults.
@@ -32,6 +33,9 @@ def create_memory(
 
     Parameters
     ----------
+    vector_index : str
+        ``auto`` (sqlite index when embedder present), ``sqlite``, ``brute``,
+        or ``off`` for full-scan retrieval.
     llm_extract : bool
         Use Ollama to extract atomic facts from conversation message lists.
     llm_domain : bool
@@ -42,13 +46,18 @@ def create_memory(
     if embeddings and similarity_fn is None:
         similarity_fn = EmbeddingSimilarity(verbose=verbose)
 
+    embed_fn = getattr(similarity_fn, "embed", None)
+
     fact_extractor = LLMFactExtractor() if llm_extract else HeuristicFactExtractor()
 
     layer_kwargs = dict(kwargs)
     if llm_domain:
         from .extract import LLMExtractor
         layer_kwargs["extractor"] = LLMExtractor()
 
+    layer_kwargs.setdefault("vector_index", vector_index)
+    layer_kwargs.setdefault("embed_fn", embed_fn)
+
     return Memory(
         user_id=user_id,
         db_path=db_path,
@@ -161,8 +170,7 @@ def delete(self, memory_id: str) -> bool:
         item = self._layer._store.get(memory_id)
         if not item or item.namespace != self.user_id:
             return False
-        self._layer._store.delete(memory_id, namespace=self.user_id)
-        return True
+        return self._layer.remove(memory_id)
 
     def clear(self) -> None:
         """Remove all memories for this user."""