feat: UTC dates, contradiction detection, access tracking

singularityjason · claude · singularityjason · commit 031adf1cc75d · 2026-03-25T08:27:21.000+08:00
All timestamps now returned as absolute ISO 8601 UTC strings
(e.g. 2026-03-25T00:00:00Z) instead of raw Unix floats.

Contradiction detection flags price changes (3x+) and sentiment
conflicts when storing memories about the same vendor.

Access tracking: query hits increment access_count and update
last_accessed_at on memories. Schema migration v3 adds columns.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/lightning_memory/db.py b/lightning_memory/db.py
@@ -5,13 +5,28 @@
 import json
 import sqlite3
 import time
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
 
 DEFAULT_DB_PATH = Path.home() / ".lightning-memory" / "memories.db"
 
 
+def format_utc(ts: float | None) -> str | None:
+    """Convert a Unix timestamp to ISO 8601 UTC string.
+
+    Returns None if input is None. All timestamps in Lightning Memory
+    are stored as Unix floats internally but exposed as absolute UTC
+    strings in API responses for unambiguous date handling.
+
+    Example: 1711324800.0 → "2024-03-25T00:00:00Z"
+    """
+    if ts is None:
+        return None
+    return datetime.fromtimestamp(ts, tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
 def _get_db_path() -> Path:
     """Return the database path, creating parent dirs if needed."""
     path = Path(DEFAULT_DB_PATH)
@@ -170,7 +185,7 @@ def store_memory(
         "type": memory_type,
         "metadata": metadata or {},
         "nostr_event_id": nostr_event_id,
-        "created_at": now,
+        "created_at": format_utc(now),
     }
 
 
@@ -210,19 +225,38 @@ def query_memories(
         )
 
     results = []
+    now = time.time()
+    hit_ids = []
     for row in rows:
+        hit_ids.append(row["id"])
         results.append({
             "id": row["id"],
             "content": row["content"],
             "type": row["type"],
             "metadata": json.loads(row["metadata"]),
             "nostr_event_id": row["nostr_event_id"],
-            "created_at": row["created_at"],
+            "created_at": format_utc(row["created_at"]),
             "relevance": -row["rank"],  # BM25 returns negative scores; negate for intuitive ordering
         })
+
+    # Update access tracking for returned memories
+    if hit_ids:
+        _bump_access(conn, hit_ids, now)
+
     return results
 
 
+def _bump_access(conn: sqlite3.Connection, memory_ids: list[str], now: float) -> None:
+    """Increment access_count and update last_accessed_at for queried memories."""
+    for mid in memory_ids:
+        conn.execute(
+            """UPDATE memories SET access_count = COALESCE(access_count, 0) + 1,
+                   last_accessed_at = ? WHERE id = ?""",
+            (now, mid),
+        )
+    conn.commit()
+
+
 def list_memories(
     conn: sqlite3.Connection,
     memory_type: str | None = None,
@@ -259,7 +293,7 @@ def list_memories(
             "type": row["type"],
             "metadata": json.loads(row["metadata"]),
             "nostr_event_id": row["nostr_event_id"],
-            "created_at": row["created_at"],
+            "created_at": format_utc(row["created_at"]),
         }
         for row in rows
     ]
@@ -316,8 +350,8 @@ def update_memory(
         "content": new_content,
         "type": row["type"],
         "metadata": existing_meta,
-        "created_at": row["created_at"],
-        "updated_at": now,
+        "created_at": format_utc(row["created_at"]),
+        "updated_at": format_utc(now),
     }
 
 
@@ -388,9 +422,12 @@ def query_by_embedding(
             "content": row["content"],
             "type": row["type"],
             "metadata": json.loads(row["metadata"]) if row["metadata"] else {},
-            "created_at": row["created_at"],
+            "created_at": format_utc(row["created_at"]),
             "similarity": round(sim, 4),
         })
+
+    # Access tracking is handled by query_memories (FTS5 path) to avoid
+    # double-counting when hybrid search calls both paths.
     return results
 
 
@@ -433,9 +470,23 @@ def _migrate_v2_add_embeddings(conn: sqlite3.Connection) -> None:
     """)
 
 
+def _migrate_v3_add_access_tracking(conn: sqlite3.Connection) -> None:
+    """v3: Add access_count and last_accessed_at to memories for staleness tracking."""
+    # SQLite ALTER TABLE only supports adding columns one at a time
+    try:
+        conn.execute("ALTER TABLE memories ADD COLUMN access_count INTEGER DEFAULT 0")
+    except sqlite3.OperationalError:
+        pass  # Column already exists
+    try:
+        conn.execute("ALTER TABLE memories ADD COLUMN last_accessed_at REAL")
+    except sqlite3.OperationalError:
+        pass  # Column already exists
+
+
 _MIGRATIONS: dict[int, callable] = {
     1: _migrate_v1_add_used_tokens,
     2: _migrate_v2_add_embeddings,
+    3: _migrate_v3_add_access_tracking,
 }
 
 
diff --git a/lightning_memory/memory.py b/lightning_memory/memory.py
@@ -130,6 +130,11 @@ def store(
         except Exception:
             pass  # Embedding failure should never block memory storage
 
+        # Check for contradictions with existing memories
+        contradictions = self._detect_contradictions(content, memory_type, metadata)
+        if contradictions:
+            result["contradictions"] = contradictions
+
         return result
 
     def query(
@@ -309,6 +314,98 @@ def _find_duplicate(
                 }
         return None
 
+    def _detect_contradictions(
+        self,
+        content: str,
+        memory_type: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Detect potential contradictions with existing memories.
+
+        For transaction/vendor memories with a vendor in metadata, checks
+        for conflicting information: different prices for same service,
+        contradictory reliability assessments, etc.
+
+        Returns a list of contradiction dicts with the conflicting memory
+        and a description of the conflict. Empty list if no contradictions.
+        """
+        if not metadata or not metadata.get("vendor"):
+            return []
+
+        vendor_norm = normalize_vendor(metadata["vendor"])
+        contradictions: list[dict[str, Any]] = []
+
+        # Only check relevant types
+        check_types = ("transaction", "vendor", "decision")
+        if memory_type not in check_types:
+            return []
+
+        rows = self.conn.execute(
+            """SELECT id, content, type, metadata, created_at
+               FROM memories WHERE type IN ('transaction', 'vendor', 'decision')
+               ORDER BY created_at DESC LIMIT 200""",
+        ).fetchall()
+
+        content_lower = content.lower()
+        new_amount = metadata.get("amount_sats")
+
+        # Sentiment indicators
+        positive_words = {"reliable", "fast", "good", "great", "excellent", "trustworthy", "recommended"}
+        negative_words = {"unreliable", "slow", "bad", "scam", "avoid", "terrible", "failed", "overpriced"}
+
+        new_positive = any(w in content_lower for w in positive_words)
+        new_negative = any(w in content_lower for w in negative_words)
+
+        for row in rows:
+            row_meta = json.loads(row["metadata"]) if row["metadata"] else {}
+            row_vendor = normalize_vendor(row_meta["vendor"]) if row_meta.get("vendor") else ""
+
+            if row_vendor != vendor_norm:
+                continue
+
+            row_content_lower = row["content"].lower()
+            old_amount = row_meta.get("amount_sats")
+
+            # Price contradiction: same vendor, significantly different price for same type of service
+            if (new_amount is not None and old_amount is not None
+                    and memory_type == "transaction" and row["type"] == "transaction"):
+                new_amt = int(new_amount)
+                old_amt = int(old_amount)
+                if old_amt > 0 and new_amt > 0:
+                    ratio = max(new_amt, old_amt) / min(new_amt, old_amt)
+                    if ratio >= 3.0:
+                        contradictions.append({
+                            "type": "price_change",
+                            "existing_id": row["id"],
+                            "existing_preview": row["content"][:100],
+                            "existing_created_at": db.format_utc(row["created_at"]),
+                            "detail": f"Price changed {ratio:.1f}x: was {old_amt} sats, now {new_amt} sats",
+                        })
+
+            # Sentiment contradiction: positive vs negative about same vendor
+            old_positive = any(w in row_content_lower for w in positive_words)
+            old_negative = any(w in row_content_lower for w in negative_words)
+
+            if new_positive and old_negative:
+                contradictions.append({
+                    "type": "sentiment_conflict",
+                    "existing_id": row["id"],
+                    "existing_preview": row["content"][:100],
+                    "existing_created_at": db.format_utc(row["created_at"]),
+                    "detail": f"New memory is positive but existing memory is negative about {vendor_norm}",
+                })
+            elif new_negative and old_positive:
+                contradictions.append({
+                    "type": "sentiment_conflict",
+                    "existing_id": row["id"],
+                    "existing_preview": row["content"][:100],
+                    "existing_created_at": db.format_utc(row["created_at"]),
+                    "detail": f"New memory is negative but existing memory is positive about {vendor_norm}",
+                })
+
+        # Limit to top 3 most relevant contradictions
+        return contradictions[:3]
+
     def _generate_id(self, content: str) -> str:
         """Generate a deterministic ID from content + timestamp."""
         raw = f"{content}:{time.time()}:{self.identity.public_key_hex}"
diff --git a/tests/test_memory_quality.py b/tests/test_memory_quality.py
