feat: add EntityMemory backend with structured key-value fact extraction (#17)

EntityMemory extracts (key, value) pairs from messages using regex patterns
matching the benchmark's injection/update templates. Facts are stored in a
dict and returned as a single system-context block on retrieval.

Key properties:
- Fact updates overwrite the stored value immediately (no stale value survives)
- Token cost scales with unique-fact count, not conversation length
- Zero LLM calls, fully deterministic and reproducible

Wired into VALID_BACKENDS, _make_memory(), and the CLI --backends flag.

Closes #12

Author: Priyanshu-byte-coder

evaluation/benchmark.py

@@ -8,6 +8,7 @@
 from memory.rag_chunked import ChunkedRAGMemory
 from memory.cascading import CascadingTemporalMemory
 from memory.summary import SummaryMemory
+from memory.entity import EntityMemory
 from memory.base import BaseMemory
 from evaluation.metrics import (
     recall_at_t, temporal_drift_score, memory_noise_ratio, precision_at_k,
@@ -21,7 +22,7 @@
 
 _NAN = float("nan")
 
-VALID_BACKENDS = ["naive", "rag", "rag_chunked", "cascading", "summary"]
+VALID_BACKENDS = ["naive", "rag", "rag_chunked", "cascading", "summary", "entity"]
 
 
 @dataclass
@@ -60,6 +61,8 @@ def _make_memory(name: str, decay: str = "ebbinghaus") -> BaseMemory:
         return CascadingTemporalMemory(decay=decay)
     if name == "summary":
         return SummaryMemory(window_size=20, use_llm=None)
+    if name == "entity":
+        return EntityMemory()
     raise ValueError(
         f"Unknown backend: '{name}'. "
         f"Choose from: {VALID_BACKENDS}"

main.py

@@ -51,7 +51,7 @@ def main() -> None:
                         default=[10, 25, 50, 75, 100])
     parser.add_argument("--backends",    nargs="+",
                         default=["naive", "rag", "cascading"],
-                        help="naive | rag | rag_chunked | cascading | summary")
+                        help="naive | rag | rag_chunked | cascading | summary | entity")
     parser.add_argument("--output",      type=str,  default="results.json")
     parser.add_argument("--log",         action="store_true",
                         help="Save run to experiment_logs/")

memory/entity.py

@@ -0,0 +1,102 @@
+"""
+memory/entity.py — Entity Memory backend for MemoryLens.
+
+Implements structured named-entity extraction: instead of storing raw message
+history, EntityMemory maintains a key-value store of extracted facts and
+returns those facts as context.  When a fact is updated, the store is patched
+in-place, so retrieval always surfaces the current value.
+
+Extraction is fully local (regex-based, no LLM call) to keep the backend fast
+and reproducible for the benchmark harness.
+
+Closes #12.
+"""
+
+import re
+from typing import Dict, List, Optional, Tuple
+from .base import BaseMemory
+
+
+# Patterns recognised by the extractor
+# Each tuple: (compiled_pattern, group_name_for_key, group_name_for_value)
+_INJECTION_RE = re.compile(
+    r"my\s+(?P<key>[a-z][a-z ]{0,30}?)\s+is\s+(?P<value>.+?)[\.\!]?\s*$",
+    re.IGNORECASE,
+)
+_UPDATE_RE = re.compile(
+    r"my\s+(?P<key>[a-z][a-z ]{0,30}?)\s+has\s+changed\s+to\s+(?P<value>.+?)[\.\!]?\s*$",
+    re.IGNORECASE,
+)
+
+
+def _extract_entity(content: str) -> Optional[Tuple[str, str]]:
+    """
+    Try to extract a (key, value) fact pair from a single message string.
+    Returns (normalised_key, value) or None if no pattern matches.
+    """
+    for pattern in (_UPDATE_RE, _INJECTION_RE):
+        m = pattern.search(content)
+        if m:
+            key = m.group("key").strip().lower()
+            val = m.group("value").strip()
+            return key, val
+    return None
+
+
+class EntityMemory(BaseMemory):
+    """
+    Structured entity-extraction memory backend.
+
+    Facts are stored as a key-value dictionary rather than as raw messages.
+    On retrieval the entire entity store is serialised into a concise context
+    block so the LLM always sees the *current* value of every known fact.
+
+    Advantages over RAG/Naive for fact-tracking tasks:
+    - O(1) update: overwriting a key replaces the fact immediately
+    - No stale value can persist once an update is absorbed
+    - Token cost is proportional to the number of unique facts, not turns
+
+    Limitations:
+    - Only captures facts matching the injection/update templates from the
+      benchmark's conversation generator; free-form facts are not extracted
+    - Does not retain conversational flow or filler turns
+
+    Reference: Entity-centric memory as described in
+    Xu et al. (2021) "Beyond Goldfish Memory" and related work on
+    structured dialogue state tracking.
+    """
+
+    name = "entity"
+
+    def __init__(self, max_facts: int = 64):
+        # Ordered so serialisation is deterministic
+        self.entities: Dict[str, str] = {}
+        self.max_facts = max_facts
+
+    def add_message(self, role: str, content: str, turn: int) -> None:
+        if role != "user":
+            return  # only extract from user utterances
+        pair = _extract_entity(content)
+        if pair:
+            key, val = pair
+            self.entities[key] = val
+            # Enforce max_facts by evicting oldest key when over limit
+            if len(self.entities) > self.max_facts:
+                oldest_key = next(iter(self.entities))
+                del self.entities[oldest_key]
+
+    def get_context(self, query: str, current_turn: int) -> List[Dict]:
+        if not self.entities:
+            return []
+
+        lines = [f"my {key} is {val}" for key, val in self.entities.items()]
+        entity_block = "; ".join(lines) + "."
+        return [
+            {
+                "role": "system",
+                "content": f"[Known facts about the user] {entity_block}",
+            }
+        ]
+
+    def reset(self) -> None:
+        self.entities = {}