dhee 7.4.3__tar.gz → 7.4.4__tar.gz

{dhee-7.4.3/dhee.egg-info → dhee-7.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dhee
-Version: 7.4.3
+Version: 7.4.4
 Summary: Dhee - world memory layer and context compiler for AI agents
 Author: Sankhya AI Labs
 License-Expression: MIT

{dhee-7.4.3 → dhee-7.4.4}/dhee/__init__.py

@@ -50,7 +50,7 @@ from dhee.memory.admission import (
 # Default import remains model-free for backwards compatibility.
 Memory = CoreMemory
 
-__version__ = "7.4.3"
+__version__ = "7.4.4"
 __all__ = [
     # Memory classes
     "Engram",

{dhee-7.4.3 → dhee-7.4.4}/dhee/core/decay.py

@@ -5,7 +5,7 @@ Uses dhee-accel (Rust) when available, pure-Python fallback otherwise.
 
 import math
 from datetime import datetime, timezone
-from typing import TYPE_CHECKING
+from typing import Any, Optional, TYPE_CHECKING
 
 if TYPE_CHECKING:
     from dhee.configs.base import FadeMemConfig
@@ -67,6 +67,36 @@ def calculate_decayed_strength(
     )
 
 
+def _as_utc(value: Any) -> Optional[datetime]:
+    if value is None or value == "":
+        return None
+    if isinstance(value, datetime):
+        moment = value
+    else:
+        try:
+            moment = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+        except ValueError:
+            return None
+    return moment if moment.tzinfo else moment.replace(tzinfo=timezone.utc)
+
+
+def decay_since(last_accessed: Any, last_decayed: Any = None) -> datetime:
+    """The moment a memory's stored strength describes.
+
+    `calculate_decayed_strength` fades the strength it is given by the time
+    elapsed since this moment. The stored strength is what the LAST decay pass
+    left — so the clock must start at that pass, not at the last access, or
+    every pass fades the already-faded strength by the whole elapsed time again
+    and forgetting compounds with how often the pass runs. Measured: a memory
+    meant to last 115 days was forgotten in under one day at a five-minute
+    cadence, and in 15 at a daily one. With the later of the two moments, any
+    number of passes over a span fades a memory exactly as one pass would.
+    """
+    accessed = _as_utc(last_accessed) or datetime.now(timezone.utc)
+    decayed = _as_utc(last_decayed)
+    return max(accessed, decayed) if decayed is not None else accessed
+
+
 def should_forget(strength: float, config: "FadeMemConfig") -> bool:
     if math.isnan(strength):
         return True

{dhee-7.4.3 → dhee-7.4.4}/dhee/db/sqlite.py

@@ -5,7 +5,8 @@ import sqlite3
 import threading
 import uuid
 from contextlib import contextmanager
-from typing import Any, Dict, List, Optional
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Set
 
 from .sqlite_analytics import SQLiteAnalyticsMixin
 from .sqlite_artifacts import SQLiteArtifactMixin
@@ -23,6 +24,52 @@ logger = logging.getLogger(__name__)
 class _SQLiteBase:
     """Base class for SQLite managers with common functionality."""
 
+    def latest_event_times(self, event: str) -> Dict[str, str]:
+        """When each memory last had `event` logged, as the history table wrote it.
+
+        Read once per decay pass, so the pass can start each memory's clock at
+        its own last decay (see `core.decay.decay_since`).
+        """
+        with self._get_connection() as conn:
+            if not getattr(self, "_history_event_index", False):
+                conn.execute(
+                    "CREATE INDEX IF NOT EXISTS idx_memory_history_event_memory "
+                    "ON memory_history(event, memory_id)"
+                )
+                self._history_event_index = True
+            rows = conn.execute(
+                "SELECT memory_id, MAX(timestamp) FROM memory_history WHERE event = ? GROUP BY memory_id",
+                (event,),
+            ).fetchall()
+        return {str(row[0]): str(row[1]) for row in rows if row[1]}
+
+    def memory_ids_holding_current_facts(self) -> Set[str]:
+        """Memories that are still the source of a fact nothing has replaced.
+
+        Forgetting a memory deletes the facts extracted from it (see
+        `_delete_memory_query_artifacts_conn`). Decay asks this first, so a
+        conversation can fade without taking "exam on 21 October" with it.
+        """
+        with self._get_connection() as conn:
+            exists = conn.execute(
+                "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'engram_facts'"
+            ).fetchone()
+            if not exists:
+                return set()
+            columns = {row[1] for row in conn.execute("PRAGMA table_info(engram_facts)")}
+            where, params = [], []
+            if "superseded_by_id" in columns:
+                where.append("superseded_by_id IS NULL")
+            if "valid_until" in columns:
+                where.append("(valid_until IS NULL OR valid_until = '' OR valid_until > ?)")
+                params.append(datetime.now(timezone.utc).isoformat())
+            rows = conn.execute(
+                "SELECT DISTINCT memory_id FROM engram_facts"
+                + (" WHERE " + " AND ".join(where) if where else ""),
+                params,
+            ).fetchall()
+        return {str(row[0]) for row in rows if row[0]}
+
     def __init__(self, db_path: str):
         self.db_path = db_path
         db_dir = os.path.dirname(db_path)

{dhee-7.4.3 → dhee-7.4.4}/dhee/memory/core.py

@@ -19,7 +19,7 @@ from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional
 
 from dhee.configs.base import MemoryConfig
-from dhee.core.decay import calculate_decayed_strength, should_forget, should_promote
+from dhee.core.decay import calculate_decayed_strength, decay_since, should_forget, should_promote
 from dhee.core.retrieval import composite_score
 from dhee.core.traces import (
     boost_fast_trace,
@@ -403,6 +403,13 @@ class CoreMemory:
             logger.warning("Vector delete failed: %s", e)
         return {"id": memory_id, "event": "DELETE"}
 
+    def _log_decay(self, mem: Dict[str, Any], new_strength: float) -> None:
+        """Record the pass, which is what the next pass starts its clock from."""
+        if callable(getattr(self.db, "log_event", None)):
+            self.db.log_event(
+                mem["id"], "DECAY", old_strength=mem.get("strength"), new_strength=new_strength
+            )
+
     def apply_decay(
         self,
         user_id: Optional[str] = None,
@@ -420,6 +427,19 @@ class CoreMemory:
         decayed = 0
         forgotten = 0
         promoted = 0
+        # Each memory's clock starts at its own last decay. See `decay_since`.
+        last_decayed = (
+            self.db.latest_event_times("DECAY")
+            if callable(getattr(self.db, "latest_event_times", None))
+            else {}
+        )
+        # A memory still the source of a current fact fades only to the
+        # threshold: forgetting it would delete the fact with it.
+        holding_facts = (
+            self.db.memory_ids_holding_current_facts()
+            if callable(getattr(self.db, "memory_ids_holding_current_facts", None))
+            else set()
+        )
 
         for mem in memories:
             if mem.get("immutable"):
@@ -438,12 +458,17 @@ class CoreMemory:
 
             new_strength = calculate_decayed_strength(
                 current_strength=float(mem.get("strength", 1.0)),
-                last_accessed=mem.get("last_accessed", mem.get("created_at", "")),
+                last_accessed=decay_since(
+                    mem.get("last_accessed", mem.get("created_at", "")),
+                    last_decayed.get(str(mem.get("id"))),
+                ),
                 access_count=int(mem.get("access_count", 0)),
                 layer=mem.get("layer", "sml"),
                 config=self.fade_config,
             )
             new_strength = enforce_quality_strength(new_strength, quality)
+            if should_forget(new_strength, self.fade_config) and str(mem.get("id")) in holding_facts:
+                new_strength = self.fade_config.forgetting_threshold
 
             if should_forget(new_strength, self.fade_config):
                 access_count = int(mem.get("access_count", 0))
@@ -486,9 +511,11 @@ class CoreMemory:
                 self.fade_config,
             ) and quality.layer == "lml" and not quality.suppress_from_default_recall:
                 self.db.update_memory(mem["id"], {"strength": new_strength, "layer": "lml"})
+                self._log_decay(mem, new_strength)
                 promoted += 1
-            else:
+            elif new_strength != float(mem.get("strength", 1.0)):
                 self.db.update_memory(mem["id"], {"strength": new_strength})
+                self._log_decay(mem, new_strength)
 
             decayed += 1
 

{dhee-7.4.3 → dhee-7.4.4}/dhee/memory/main.py

@@ -17,7 +17,7 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple, Union
 
 from dhee.configs.base import MemoryConfig
-from dhee.core.decay import calculate_decayed_strength, should_forget, should_promote
+from dhee.core.decay import calculate_decayed_strength, decay_since, should_forget, should_promote
 from dhee.core.conflict import resolve_conflict
 from dhee.core.distillation import ReplayDistiller
 from dhee.core.echo import EchoProcessor, EchoDepth, EchoResult
@@ -1523,10 +1523,28 @@ class FullMemory(SmartMemory, SceneProfileMixin):
         decayed = 0
         forgotten = 0
         promoted = 0
+        # Each memory's clock starts at its own last decay, not its last
+        # access: the stored strength is what that pass left. See `decay_since`.
+        last_decayed = (
+            self.db.latest_event_times("DECAY")
+            if callable(getattr(self.db, "latest_event_times", None))
+            else {}
+        )
+        # Forgetting a memory deletes the facts extracted from it, so one that
+        # is still the source of a current fact fades only to the threshold.
+        holding_facts = (
+            self.db.memory_ids_holding_current_facts()
+            if callable(getattr(self.db, "memory_ids_holding_current_facts", None))
+            else set()
+        )
 
         for memory in memories:
             if memory.get("immutable"):
                 continue
+            since = decay_since(
+                memory.get("last_accessed", memory.get("created_at")),
+                last_decayed.get(str(memory.get("id"))),
+            )
 
             # Shruti-tier memories are immune to decay
             _tier_md = memory.get("metadata") or {}
@@ -1573,7 +1591,7 @@ class FullMemory(SmartMemory, SceneProfileMixin):
                     s_fast=float(memory.get("s_fast", 0.0)),
                     s_mid=float(memory.get("s_mid", 0.0)),
                     s_slow=float(memory.get("s_slow", 0.0)),
-                    last_accessed=memory.get("last_accessed", datetime.now(timezone.utc).isoformat()),
+                    last_accessed=since,
                     access_count=memory.get("access_count", 0),
                     config=self.distillation_config,
                 )
@@ -1581,7 +1599,7 @@ class FullMemory(SmartMemory, SceneProfileMixin):
             else:
                 new_strength = calculate_decayed_strength(
                     current_strength=memory.get("strength", 1.0),
-                    last_accessed=memory.get("last_accessed", datetime.now(timezone.utc).isoformat()),
+                    last_accessed=since,
                     access_count=memory.get("access_count", 0),
                     layer=memory.get("layer", "sml"),
                     config=self.fade_config,
@@ -1598,6 +1616,8 @@ class FullMemory(SmartMemory, SceneProfileMixin):
                 weak = min(int(ref_state.get("weak", 0)), 10)
                 forget_threshold = forget_threshold / (1.0 + weak * 0.25)
 
+            if new_strength < forget_threshold and str(memory.get("id")) in holding_facts:
+                new_strength = forget_threshold
             if new_strength < forget_threshold:
                 self.delete(memory["id"])
                 forgotten += 1

{dhee-7.4.3 → dhee-7.4.4/dhee.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dhee
-Version: 7.4.3
+Version: 7.4.4
 Summary: Dhee - world memory layer and context compiler for AI agents
 Author: Sankhya AI Labs
 License-Expression: MIT

{dhee-7.4.3 → dhee-7.4.4}/dhee.egg-info/SOURCES.txt

@@ -438,6 +438,7 @@ tests/test_corpus_tree.py
 tests/test_cosine_similarity.py
 tests/test_data_dir_paths.py
 tests/test_decades_eval.py
+tests/test_decay_cadence.py
 tests/test_decisions.py
 tests/test_dedup.py
 tests/test_deferred_enrichment.py

{dhee-7.4.3 → dhee-7.4.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dhee"
-version = "7.4.3"
+version = "7.4.4"
 description = "Dhee - world memory layer and context compiler for AI agents"
 readme = "README.md"
 requires-python = ">=3.9"

dhee-7.4.4/tests/test_decay_cadence.py

@@ -0,0 +1,135 @@
+"""Forgetting depends on time, not on how often the decay pass runs.
+
+`calculate_decayed_strength` fades the CURRENT strength by the time since the
+memory was last accessed. Applied once, that is right. Applied again on the
+next pass, it fades the already-faded strength by the whole elapsed time again,
+so the result compounds with every run. Tura runs the pass every five minutes;
+measured with this module's own function, a memory meant to last 115 days was
+forgotten in under one, and on production (2026-10-07) none of the 12 students
+who had studied in the previous fortnight had a single memory left.
+"""
+
+import math
+import os
+from datetime import datetime, timedelta, timezone
+
+import pytest
+
+from dhee import CoreMemory
+
+def _ago(days):
+    return (datetime.now(timezone.utc) - timedelta(days=days)).isoformat()
+
+
+def _memory(factory, data_dir):
+    # A store of its own: a shared one dedupes the text and keeps old DECAY events.
+    os.environ["DHEE_DATA_DIR"] = str(data_dir)
+    if factory == "core":
+        return CoreMemory(preset="minimal")
+    from dhee.memory.main import FullMemory
+
+    return FullMemory(preset="minimal")
+
+
+def _aged(memory, text, days):
+    try:
+        added = memory.add(text, user_id="student", infer=False)
+    except TypeError:  # CoreMemory never infers, and takes no such argument
+        added = memory.add(text, user_id="student")
+    memory_id = added["results"][0]["id"]
+    memory.db.update_memory(memory_id, {"last_accessed": _ago(days), "strength": 1.0})
+    return memory_id
+
+
+def _strength_after(tmp_path, factory, passes, days):
+    memory = _memory(factory, tmp_path / f"{factory}-{passes}-{days}")
+    try:
+        memory_id = _aged(memory, "Prefers derivations before worked examples", days)
+        for _ in range(passes):
+            memory.apply_decay(scope={"user_id": "student"})
+        row = memory.db.get_memory(memory_id)
+        return None if row is None or row.get("tombstone") else float(row["strength"])
+    finally:
+        memory.close()
+
+
+@pytest.mark.parametrize("factory", ["core", "full"])
+def test_thirty_passes_fade_a_memory_as_much_as_one(tmp_path, monkeypatch, factory):
+    monkeypatch.setenv("DHEE_DATA_DIR", str(tmp_path))
+    # Old enough to fade, young enough that one pass keeps it.
+    once = _strength_after(tmp_path, factory, 1, days=2)
+    assert once is not None and once < 1.0, "the fixture must fade, and survive one pass"
+    thirty = _strength_after(tmp_path, factory, 30, days=2)
+    assert thirty is not None, "thirty passes forgot what one pass keeps"
+    assert math.isclose(thirty, once, abs_tol=0.01), f"one pass leaves {once:.3f}, thirty leave {thirty:.3f}"
+
+
+def test_a_memory_still_fades_with_time(tmp_path, monkeypatch):
+    """The fix must not stop forgetting: a pass long after the last one fades it."""
+    monkeypatch.setenv("DHEE_DATA_DIR", str(tmp_path))
+    assert (_strength_after(tmp_path, "core", 1, days=2) or 0.0) < 1.0
+    assert (_strength_after(tmp_path, "full", 1, days=2) or 0.0) < 1.0
+
+
+def _hold_fact(memory, memory_id, value="21 October"):
+    """A fact extracted from `memory_id`, as the extractor would have stored it."""
+    import uuid
+
+    fact_id = str(uuid.uuid4())
+    with memory.db._get_connection() as conn:
+        conn.execute(
+            "INSERT INTO engram_facts (id, memory_id, subject, predicate, value, canonical_key) "
+            "VALUES (?, ?, 'user', 'exam_on', ?, ?)",
+            (fact_id, memory_id, f"computational stats: {value}", f"user|exam_on|{value}"),
+        )
+    return fact_id
+
+
+def _facts_from(memory, memory_id):
+    with memory.db._get_connection() as conn:
+        return conn.execute(
+            "SELECT count(*) FROM engram_facts WHERE memory_id = ?", (memory_id,)
+        ).fetchone()[0]
+
+
+@pytest.mark.parametrize("factory", ["core", "full"])
+def test_a_memory_holding_a_current_fact_is_not_forgotten(tmp_path, monkeypatch, factory):
+    """Forgetting a memory deletes its facts; decay must not take a current one.
+
+    Measured on production 2026-09-30: a student's "exam date is 21 october"
+    was extracted and kept by the gate, then deleted with its conversation
+    when decay forgot it. One of 38 student stores held any fact a week later.
+    """
+    monkeypatch.setenv("DHEE_DATA_DIR", str(tmp_path))
+    memory = _memory(factory, tmp_path / factory)
+    try:
+        memory_id = _aged(memory, "The subject is computational stats and the exam is on 21 October", 2000)
+        _hold_fact(memory, memory_id)
+        memory.apply_decay(scope={"user_id": "student"})
+        row = memory.db.get_memory(memory_id)
+        assert row is not None and not row.get("tombstone"), "a memory holding a current fact was forgotten"
+        assert _facts_from(memory, memory_id) == 1
+        assert float(row["strength"]) == pytest.approx(memory.fade_config.forgetting_threshold)
+
+        # Once the fact is replaced, the memory fades like any other. Time
+        # passes for the last decay too: the clock now starts there.
+        with memory.db._get_connection() as conn:
+            conn.execute("UPDATE engram_facts SET superseded_by_id = 'newer' WHERE memory_id = ?", (memory_id,))
+            conn.execute("UPDATE memory_history SET timestamp = ? WHERE memory_id = ?", (_ago(2000), memory_id))
+        memory.apply_decay(scope={"user_id": "student"})
+        row = memory.db.get_memory(memory_id)
+        assert row is None or row.get("tombstone"), "a memory whose facts were replaced was kept"
+    finally:
+        memory.close()
+
+
+def test_a_memory_with_no_facts_is_still_forgotten(tmp_path, monkeypatch):
+    monkeypatch.setenv("DHEE_DATA_DIR", str(tmp_path))
+    memory = _memory("full", tmp_path / "plain")
+    try:
+        memory_id = _aged(memory, "Said hello and left", 2000)
+        memory.apply_decay(scope={"user_id": "student"})
+        row = memory.db.get_memory(memory_id)
+        assert row is None or row.get("tombstone")
+    finally:
+        memory.close()