Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

fix(context): stamp AgentMemory in aware UTC, not mixed naive conventions (#1073)

yzxcj7976afe90e4fb6c
diff --git a/semantica/context/agent_memory.py b/semantica/context/agent_memory.py
index 371721bf..b7689ba7 100644
--- a/semantica/context/agent_memory.py
+++ b/semantica/context/agent_memory.py
@@ -152,9 +152,9 @@ class MemoryItem:
"""Reconstruct a MemoryItem from a serialised dict."""
raw_ts = data.get("timestamp")
try:
- ts = datetime.fromisoformat(raw_ts) if raw_ts else datetime.utcnow()
+ ts = datetime.fromisoformat(raw_ts) if raw_ts else datetime.now(timezone.utc)
except (ValueError, TypeError):
- ts = datetime.utcnow()
+ ts = datetime.now(timezone.utc)
return cls(
content=data.get("content", ""),
timestamp=ts,
@@ -355,7 +355,14 @@ class AgentMemory:
try:
memory_id = options.get("memory_id") or self._generate_memory_id()
- timestamp = options.get("timestamp") or datetime.now()
+ # Aware UTC, deliberately: _timestamp_comparison_key interprets a
+ # naive stamp as LOCAL time, so a naive local "now" here and a
+ # naive utcnow() elsewhere differ by the host's UTC offset — on a
+ # UTC+8 host that pushed freshly added memories 8 hours outside
+ # every start_date/end_date window. One aware producer removes
+ # the ambiguity; legacy naive stamps keep their local-time
+ # meaning through the comparison key.
+ timestamp = options.get("timestamp") or datetime.now(timezone.utc)
if memory_id in self.memory_items:
replacement_options = dict(options)
@@ -1073,7 +1080,7 @@ class AgentMemory:
else:
days = 30
- cutoff_date = datetime.now() - timedelta(days=days)
+ cutoff_date = datetime.now(timezone.utc) - timedelta(days=days)
# Delete old items
memory_ids_to_delete = []
diff --git a/tests/context/test_agent_memory_timestamps.py b/tests/context/test_agent_memory_timestamps.py
new file mode 100644
index 00000000..ca3f1165
--- /dev/null
+++ b/tests/context/test_agent_memory_timestamps.py
@@ -0,0 +1,123 @@
+"""Timestamp semantics for AgentMemory (#found-by-audit).
+
+MemoryItem timestamps had two producers with different naive conventions:
+``store()`` defaulted to ``datetime.now()`` (naive LOCAL) while ``from_dict``
+fell back to ``datetime.utcnow()`` (naive UTC). ``_timestamp_comparison_key``
+interprets every naive stamp as LOCAL time, so on any host off UTC the two
+producers disagree by the host's offset — a UTC+8 host pushed freshly added
+memories 8 hours outside every ``start_date``/``end_date`` window, and
+``cleanup_old_memories`` aged them wrong by the same amount.
+
+The contract pinned here:
+
+* every NEW stamp the module produces is timezone-aware UTC;
+* legacy naive stamps keep their documented local-time meaning through the
+ comparison key (it must not flip to interpreting naive as UTC);
+* aware stamps compare correctly against naive and aware boundaries alike,
+ on hosts in any timezone.
+"""
+
+import sys
+import os
+import unittest
+from datetime import datetime, timedelta, timezone
+
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..")))
+
+from semantica.context.agent_memory import AgentMemory, MemoryItem
+
+
+def host_offset() -> timedelta:
+ return datetime.now().astimezone().utcoffset() or timedelta(0)
+
+
+class TestAwareUtcProducers(unittest.TestCase):
+ def test_store_default_timestamp_is_aware_utc(self):
+ memory = AgentMemory()
+ memory.store("recall me")
+
+ item = next(iter(memory.memory_items.values()))
+ self.assertIsNotNone(item.timestamp.tzinfo, "store() must not produce naive stamps")
+ self.assertEqual(item.timestamp.utcoffset(), timedelta(0), "store() must stamp UTC, not local")
+
+ def test_from_dict_missing_timestamp_is_aware_utc(self):
+ item = MemoryItem.from_dict({"content": "reconstructed"})
+ self.assertIsNotNone(item.timestamp.tzinfo)
+ self.assertEqual(item.timestamp.utcoffset(), timedelta(0))
+
+ def test_round_trip_preserves_the_instant(self):
+ memory = AgentMemory()
+ memory.store("persisted")
+ original = next(iter(memory.memory_items.values()))
+
+ restored = MemoryItem.from_dict(original.to_dict())
+
+ self.assertEqual(
+ restored.timestamp,
+ original.timestamp,
+ "isoformat() must round-trip the exact instant for the comparison key to stay truthful",
+ )
+
+
+class TestComparisonKeySemantics(unittest.TestCase):
+ def test_naive_stamps_keep_their_local_time_meaning(self):
+ # _timestamp_comparison_key documents naive-as-local. If it silently
+ # flips to naive-as-UTC, every legacy persisted stamp shifts by the
+ # host offset — the same class of drift this file exists for, in the
+ # other direction.
+ naive = datetime(2026, 1, 1, 12, 0, 0)
+ self.assertEqual(
+ AgentMemory._timestamp_comparison_key(naive),
+ naive.astimezone(timezone.utc),
+ )
+
+ def test_aware_utc_stamp_is_not_shifted(self):
+ aware = datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc)
+ self.assertEqual(
+ AgentMemory._timestamp_comparison_key(aware),
+ aware,
+ )
+
+
+class TestDateRangeFiltering(unittest.TestCase):
+ def test_freshly_added_memory_is_inside_a_utc_window_around_now(self):
+ # The regression, end to end: a memory added "now" must land inside a
+ # start_date/end_date window expressed in UTC around now. With the
+ # naive-local producer this fails by exactly the host offset on every
+ # non-UTC host.
+ memory = AgentMemory()
+ memory.store("window probe")
+ now = datetime.now(timezone.utc)
+
+ results = memory.retrieve(
+ "probe",
+ max_results=10,
+ start_date=(now - timedelta(minutes=5)).isoformat(),
+ end_date=(now + timedelta(minutes=5)).isoformat(),
+ )
+
+ self.assertTrue(
+ any(r.get("content") == "window probe" for r in results),
+ f"memory added now must be within the UTC window (host offset {host_offset()})",
+ )
+
+ def test_explicit_utc_boundary_excludes_older_stamps(self):
+ memory = AgentMemory()
+ old = datetime(2020, 1, 1, tzinfo=timezone.utc)
+ memory.store("old memory", timestamp=old)
+ boundary = datetime(2025, 1, 1, tzinfo=timezone.utc)
+
+ results = memory.retrieve(
+ "memory",
+ max_results=10,
+ start_date=boundary.isoformat(),
+ )
+
+ self.assertFalse(
+ any(r.get("content") == "old memory" for r in results),
+ "a 2020 stamp must not match a window starting in 2025, whatever the host timezone",
+ )
+
+
+if __name__ == "__main__":
+ unittest.main()