feat(decay): kind-aware boost (episodic by default)

Semantic facts and procedural how-tos are largely timeless: demoting
them on age is wrong by construction. Restrict the freshness boost
to ``MemoryKind.EPISODIC`` by default, with ``decay_kinds_csv`` on
``MarvinSettings`` so deployments can opt other kinds in (e.g.,
``"episodic,procedural"`` for vaults where runbooks really do go
stale, or ``"all"`` to apply decay to everything).

Author: r0k3

docs/guide/evaluation.md

@@ -149,6 +149,14 @@ their honest RRF rank. See `marvin.decay` for the formula.
 | `decay_enabled` | `false` | toggle the freshness boost |
 | `decay_half_life_days` | `30.0` | exponential half-life (days) |
 | `decay_weight` | `0.5` | maximum boost (1.0 = double the score for an instant-old note) |
+| `decay_kinds_csv` | `"episodic"` | comma-separated kinds the boost applies to (`"episodic,procedural"`, `"all"`, `""`) |
+
+The kind filter exists because semantic facts ("Berlin is the capital
+of Germany") and procedural how-tos ("how to deploy the staging
+service") are largely timeless: a 12-month-old fact is just as true as
+a fresh one, so demoting it on age is wrong by construction. Episodic
+chat sessions, by contrast, have a strong recency prior. The default
+``decay_kinds_csv = "episodic"`` mirrors that intuition.
 
 LongMemEval-S impact (n=30, `--question-type knowledge-update`,
 hybrid no-rerank):

src/marvin/config.py

@@ -73,6 +73,14 @@ class MarvinSettings(BaseSettings):
     decay_enabled: bool = Field(default=False)
     decay_half_life_days: float = Field(default=30.0, gt=0.0)
     decay_weight: float = Field(default=0.5, ge=0.0)
+    # Comma-separated list of note kinds the freshness boost applies
+    # to. Default is ``"episodic"`` because semantic facts and
+    # procedural how-tos are (mostly) timeless and shouldn't be
+    # demoted purely for being old. Set to ``"episodic,procedural"``
+    # for vaults that treat procedures as time-sensitive (deployment
+    # runbooks, dependency notes), or ``""`` to apply decay to no
+    # kind (effectively disabling it without flipping the toggle).
+    decay_kinds_csv: str = Field(default="episodic")
 
     # At-ingest entity extraction. Augments ``metadata.links`` (which
     # only carries explicit ``[[wikilinks]]`` produced by the

src/marvin/index.py

@@ -122,6 +122,7 @@ def __init__(
         decay_enabled: bool = False,
         decay_half_life_days: float = 30.0,
         decay_weight: float = 0.5,
+        decay_kinds: frozenset[MemoryKind] | None = None,
     ) -> None:
         self.db_path = db_path
         self.dimensions = dimensions
@@ -152,11 +153,21 @@ def __init__(
         # Time-aware boost over the final note ranking. Off by default
         # (opt-in via settings) so existing behaviour is unchanged.
         # ``decay_weight`` caps the multiplicative boost; setting it to
-        # 0 disables decay even when ``decay_enabled`` is True. See
-        # :mod:`marvin.decay` for the rationale.
+        # 0 disables decay even when ``decay_enabled`` is True.
+        # ``decay_kinds`` restricts the boost to specific note kinds --
+        # default is EPISODIC only because semantic, procedural, and
+        # reflective notes encode (mostly) timeless content where
+        # "fresher = better" doesn't hold. Pass ``frozenset(MemoryKind)``
+        # to apply decay to every kind. See :mod:`marvin.decay` for the
+        # rationale.
         self.decay_enabled = decay_enabled
         self.decay_half_life_days = max(1e-3, decay_half_life_days)
         self.decay_weight = max(0.0, decay_weight)
+        self.decay_kinds: frozenset[MemoryKind] = (
+            decay_kinds
+            if decay_kinds is not None
+            else frozenset({MemoryKind.EPISODIC})
+        )
         self.db_path.parent.mkdir(parents=True, exist_ok=True)
         self.conn = sqlite3.connect(self.db_path)
         self.conn.row_factory = sqlite3.Row
@@ -531,9 +542,10 @@ def _apply_decay_boost(
     ) -> None:
         """Mutate ``scores`` in place with a freshness multiplier.
 
-        Pulls ``updated_at`` for the candidate paths in a single query
-        rather than threading the timestamp through every row in every
-        first-stage stream. Notes whose ``updated_at`` cannot be parsed
+        Pulls ``updated_at`` and ``kind`` for the candidate paths in a
+        single query rather than threading the timestamp through every
+        row in every first-stage stream. Notes whose ``updated_at``
+        cannot be parsed, or whose kind isn't in :attr:`decay_kinds`,
         are left untouched (multiplier = 1.0), matching the no-op
         contract of :func:`marvin.decay.freshness_boost`.
         """
@@ -542,11 +554,18 @@ def _apply_decay_boost(
         paths = list(scores.keys())
         placeholders = ",".join("?" for _ in paths)
         rows = self.conn.execute(
-            f"SELECT relative_path, updated_at FROM notes "
+            f"SELECT relative_path, kind, updated_at FROM notes "
             f"WHERE relative_path IN ({placeholders})",
             paths,
         ).fetchall()
+        kinds = self.decay_kinds
         for row in rows:
+            try:
+                kind = MemoryKind(row["kind"])
+            except ValueError:
+                continue
+            if kind not in kinds:
+                continue
             note_time = parse_note_timestamp(row["updated_at"])
             if note_time is None:
                 continue

src/marvin/service.py

@@ -19,6 +19,29 @@
     SessionContext,
     SyncReport,
 )
+
+
+def _parse_decay_kinds(csv: str) -> frozenset[MemoryKind] | None:
+    """Decode the ``decay_kinds_csv`` setting.
+
+    Empty string => ``frozenset()`` (decay applies to no kind).
+    The literal token ``all`` => ``None`` so the index falls back to
+    its default (currently ``EPISODIC`` only) without enumerating
+    each kind here.
+    """
+    text = csv.strip().lower()
+    if not text:
+        return frozenset()
+    if text == "all":
+        return frozenset(MemoryKind)
+    parts = [p.strip() for p in text.split(",") if p.strip()]
+    out: set[MemoryKind] = set()
+    for token in parts:
+        try:
+            out.add(MemoryKind(token))
+        except ValueError:
+            continue
+    return frozenset(out) if out else frozenset()
 from .reranker import RerankerService
 from .vault import VaultStore, normalize_links, normalize_tags
 
@@ -63,6 +86,7 @@ def __init__(
             decay_enabled=self.settings.decay_enabled,
             decay_half_life_days=self.settings.decay_half_life_days,
             decay_weight=self.settings.decay_weight,
+            decay_kinds=_parse_decay_kinds(self.settings.decay_kinds_csv),
         )
 
     def close(self) -> None:

tests/test_index.py

@@ -1072,6 +1072,94 @@ def test_enabled_with_zero_weight_is_noop(self) -> None:
         finally:
             index.close()
 
+    def test_decay_kinds_filter_excludes_semantic(self) -> None:
+        """Semantic facts are timeless; the default decay_kinds is
+        ``{EPISODIC}`` so a fresh semantic note should NOT outrank an
+        old semantic note on the basis of recency alone."""
+        index = MemoryIndex(
+            Path(":memory:"),
+            dimensions=8,
+            decay_enabled=True,
+            decay_half_life_days=30.0,
+            decay_weight=0.5,
+        )
+        try:
+            now = datetime(2025, 1, 10, 12, 0, tzinfo=UTC)
+            old = now - timedelta(days=365)
+            for path, ts in (("old", old), ("new", now)):
+                meta = NoteMetadata(
+                    kind=MemoryKind.SEMANTIC,
+                    title=path,
+                    created_at=ts,
+                    updated_at=ts,
+                )
+                note = NoteRecord(
+                    path=Path(f"{path}.md"),
+                    metadata=meta,
+                    body="the quokka is a marsupial",
+                    raw_text="",
+                )
+                chunks = chunk_markdown(note, 1200, 200)
+                index.upsert_note(
+                    note,
+                    path,
+                    chunks=chunks,
+                    embeddings=_empty_embeds(len(chunks)),
+                )
+            hits = index.hybrid_search(
+                query="quokka marsupial",
+                query_embedding=np.zeros(8, dtype=np.float32),
+                limit=5,
+                query_time=now,
+            )
+            assert {h.path for h in hits} == {"old", "new"}
+        finally:
+            index.close()
+
+    def test_decay_kinds_explicit_includes_semantic(self) -> None:
+        """When the caller explicitly passes ``frozenset({SEMANTIC})``
+        the kind filter inverts and semantic notes do get the boost."""
+        index = MemoryIndex(
+            Path(":memory:"),
+            dimensions=8,
+            decay_enabled=True,
+            decay_half_life_days=30.0,
+            decay_weight=0.5,
+            decay_kinds=frozenset({MemoryKind.SEMANTIC}),
+        )
+        try:
+            now = datetime(2025, 1, 10, 12, 0, tzinfo=UTC)
+            old = now - timedelta(days=365)
+            for path, ts in (("old", old), ("new", now)):
+                meta = NoteMetadata(
+                    kind=MemoryKind.SEMANTIC,
+                    title=path,
+                    created_at=ts,
+                    updated_at=ts,
+                )
+                note = NoteRecord(
+                    path=Path(f"{path}.md"),
+                    metadata=meta,
+                    body="the quokka is a marsupial",
+                    raw_text="",
+                )
+                chunks = chunk_markdown(note, 1200, 200)
+                index.upsert_note(
+                    note,
+                    path,
+                    chunks=chunks,
+                    embeddings=_empty_embeds(len(chunks)),
+                )
+            hits = index.hybrid_search(
+                query="quokka marsupial",
+                query_embedding=np.zeros(8, dtype=np.float32),
+                limit=5,
+                query_time=now,
+            )
+            assert hits[0].path == "new"
+        finally:
+            index.close()
+
     def test_query_time_default_is_now(self) -> None:
         """Omitting ``query_time`` falls back to the index server's
         ``utc_now``, so a recent note still gets a boost over an old one