feat: expand short recency parameter names to descriptive ones

- Update core algorithms to use descriptive names (freshness_weight, novelty_weight, etc.)
- Add backward compatibility for old short names (wf, wa, w_sem, w_recency)
- Update API models with new descriptive field names while preserving old ones
- Add helper function to build recency params with fallback to old names
- Update tests to demonstrate new preferred parameter naming
- Internal functions now use clear variable names (semantic_weight vs w_sem)

Old names still work for backward compatibility:
- wf → freshness_weight
- wa → novelty_weight
- w_sem → semantic_weight
- w_recency → recency_weight

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: abrookins

agent_memory_server/api.py

@@ -1,3 +1,5 @@
+from typing import Any
+
 import tiktoken
 from fastapi import APIRouter, Depends, HTTPException, Query
 from mcp.server.fastmcp.prompts import base
@@ -128,6 +130,54 @@ def _calculate_context_usage_percentages(
     return min(total_percentage, 100.0), min(until_summarization_percentage, 100.0)
 
 
+def _build_recency_params(payload: SearchRequest) -> dict[str, Any]:
+    """Build recency parameters dict with backward compatibility.
+
+    Prefers new descriptive parameter names over old short names.
+    """
+    # Use new parameter names if available, fall back to old ones, then defaults
+    semantic_weight = (
+        payload.recency_semantic_weight
+        if payload.recency_semantic_weight is not None
+        else (payload.recency_w_sem if payload.recency_w_sem is not None else 0.8)
+    )
+    recency_weight = (
+        payload.recency_recency_weight
+        if payload.recency_recency_weight is not None
+        else (
+            payload.recency_w_recency if payload.recency_w_recency is not None else 0.2
+        )
+    )
+    freshness_weight = (
+        payload.recency_freshness_weight
+        if payload.recency_freshness_weight is not None
+        else (payload.recency_wf if payload.recency_wf is not None else 0.6)
+    )
+    novelty_weight = (
+        payload.recency_novelty_weight
+        if payload.recency_novelty_weight is not None
+        else (payload.recency_wa if payload.recency_wa is not None else 0.4)
+    )
+
+    return {
+        # Use new descriptive names internally
+        "semantic_weight": semantic_weight,
+        "recency_weight": recency_weight,
+        "freshness_weight": freshness_weight,
+        "novelty_weight": novelty_weight,
+        "half_life_last_access_days": (
+            payload.recency_half_life_last_access_days
+            if payload.recency_half_life_last_access_days is not None
+            else 7.0
+        ),
+        "half_life_created_days": (
+            payload.recency_half_life_created_days
+            if payload.recency_half_life_created_days is not None
+            else 30.0
+        ),
+    }
+
+
 async def _summarize_working_memory(
     memory: WorkingMemory,
     model_name: ModelNameLiteral | None = None,
@@ -558,25 +608,8 @@ async def search_long_term_memory(
         else False
     )
     if server_side_recency:
-        recency_params = {
-            "w_sem": payload.recency_w_sem
-            if payload.recency_w_sem is not None
-            else 0.8,
-            "w_recency": payload.recency_w_recency
-            if payload.recency_w_recency is not None
-            else 0.2,
-            "wf": payload.recency_wf if payload.recency_wf is not None else 0.6,
-            "wa": payload.recency_wa if payload.recency_wa is not None else 0.4,
-            # map half-life to smoothing constants server-side if needed
-            "half_life_last_access_days": payload.recency_half_life_last_access_days
-            if payload.recency_half_life_last_access_days is not None
-            else 7.0,
-            "half_life_created_days": payload.recency_half_life_created_days
-            if payload.recency_half_life_created_days is not None
-            else 30.0,
-        }
         kwargs["server_side_recency"] = True
-        kwargs["recency_params"] = recency_params
+        kwargs["recency_params"] = _build_recency_params(payload)
         return await long_term_memory.search_long_term_memories(**kwargs)
 
     raw_results = await long_term_memory.search_long_term_memories(**kwargs)

agent_memory_server/long_term_memory.py

@@ -1383,28 +1383,32 @@ def score_recency(
 ) -> float:
     """Compute a recency score in [0, 1] combining freshness and novelty.
 
-    - freshness f decays with last_accessed using half-life `half_life_last_access_days`
-    - novelty a decays with created_at using half-life `half_life_created_days`
-    - r = wf * f + wa * a
+    - freshness decays with last_accessed using half-life `half_life_last_access_days`
+    - novelty decays with created_at using half-life `half_life_created_days`
+    - recency = freshness_weight * freshness + novelty_weight * novelty
     """
-    half_life_la = max(float(params.get("half_life_last_access_days", 7.0)), 0.001)
-    half_life_cr = max(float(params.get("half_life_created_days", 30.0)), 0.001)
-    wf = float(params.get("wf", 0.6))
-    wa = float(params.get("wa", 0.4))
+    half_life_last_access = max(
+        float(params.get("half_life_last_access_days", 7.0)), 0.001
+    )
+    half_life_created = max(float(params.get("half_life_created_days", 30.0)), 0.001)
+
+    # Support both old and new parameter names for backward compatibility
+    freshness_weight = float(params.get("freshness_weight", params.get("wf", 0.6)))
+    novelty_weight = float(params.get("novelty_weight", params.get("wa", 0.4)))
 
     # Convert to decay rates
-    mu = log(2.0) / half_life_la
-    lam = log(2.0) / half_life_cr
+    access_decay_rate = log(2.0) / half_life_last_access
+    creation_decay_rate = log(2.0) / half_life_created
 
     days_since_access = _days_between(now, memory.last_accessed)
     days_since_created = _days_between(now, memory.created_at)
 
-    f = exp(-mu * days_since_access)
-    a = exp(-lam * days_since_created)
+    freshness = exp(-access_decay_rate * days_since_access)
+    novelty = exp(-creation_decay_rate * days_since_created)
 
-    r = wf * f + wa * a
+    recency_score = freshness_weight * freshness + novelty_weight * novelty
     # Clamp to [0, 1]
-    return max(0.0, min(1.0, r))
+    return max(0.0, min(1.0, recency_score))
 
 
 def rerank_with_recency(
@@ -1415,15 +1419,16 @@ def rerank_with_recency(
 ) -> list[MemoryRecordResult]:
     """Re-rank results using combined semantic similarity and recency.
 
-    score = w_sem * (1 - dist) + w_recency * recency_score
+    score = semantic_weight * (1 - dist) + recency_weight * recency_score
     """
-    w_sem = float(params.get("w_sem", 0.8))
-    w_rec = float(params.get("w_recency", 0.2))
+    # Support both old and new parameter names for backward compatibility
+    semantic_weight = float(params.get("semantic_weight", params.get("w_sem", 0.8)))
+    recency_weight = float(params.get("recency_weight", params.get("w_recency", 0.2)))
 
     def combined_score(mem: MemoryRecordResult) -> float:
-        sim = 1.0 - float(mem.dist)
-        rec = score_recency(mem, now=now, params=params)
-        return w_sem * sim + w_rec * rec
+        similarity = 1.0 - float(mem.dist)
+        recency = score_recency(mem, now=now, params=params)
+        return semantic_weight * similarity + recency_weight * recency
 
     # Sort by descending score (stable sort preserves original order on ties)
     return sorted(results, key=combined_score, reverse=True)
@@ -1507,10 +1512,10 @@ def select_ids_for_forgetting(
     # Budget-based pruning (keep top N by recency among eligible)
     if isinstance(budget, int) and budget >= 0 and budget < len(eligible_for_budget):
         params = {
-            "w_sem": 0.0,  # budget considers only recency
-            "w_recency": 1.0,
-            "wf": 0.6,
-            "wa": 0.4,
+            "semantic_weight": 0.0,  # budget considers only recency
+            "recency_weight": 1.0,
+            "freshness_weight": 0.6,
+            "novelty_weight": 0.4,
             "half_life_last_access_days": 7.0,
             "half_life_created_days": 30.0,
         }

agent_memory_server/models.py

@@ -390,6 +390,25 @@ class SearchRequest(BaseModel):
     recency_half_life_created_days: float | None = Field(
         default=None, description="Half-life (days) for created_at decay"
     )
+
+    # New descriptive parameter names (preferred over short names above)
+    recency_semantic_weight: float | None = Field(
+        default=None,
+        description="Weight for semantic similarity (preferred over recency_w_sem)",
+    )
+    recency_recency_weight: float | None = Field(
+        default=None,
+        description="Weight for recency score (preferred over recency_w_recency)",
+    )
+    recency_freshness_weight: float | None = Field(
+        default=None,
+        description="Weight for freshness component (preferred over recency_wf)",
+    )
+    recency_novelty_weight: float | None = Field(
+        default=None,
+        description="Weight for novelty (age) component (preferred over recency_wa)",
+    )
+
     # Server-side recency rerank (Redis-only path) toggle
     server_side_recency: bool | None = Field(
         default=None,

agent_memory_server/utils/redis_query.py

@@ -56,20 +56,24 @@ def apply_recency(
         self, *, now_ts: int, params: dict[str, Any] | None = None
     ) -> RecencyAggregationQuery:
         params = params or {}
-        w_sem = float(params.get("w_sem", 0.8))
-        w_rec = float(params.get("w_recency", 0.2))
-        wf = float(params.get("wf", 0.6))
-        wa = float(params.get("wa", 0.4))
-        hl_la = float(params.get("half_life_last_access_days", 7.0))
-        hl_cr = float(params.get("half_life_created_days", 30.0))
+
+        # Support both old and new parameter names for backward compatibility
+        semantic_weight = float(params.get("semantic_weight", params.get("w_sem", 0.8)))
+        recency_weight = float(
+            params.get("recency_weight", params.get("w_recency", 0.2))
+        )
+        freshness_weight = float(params.get("freshness_weight", params.get("wf", 0.6)))
+        novelty_weight = float(params.get("novelty_weight", params.get("wa", 0.4)))
+        half_life_access = float(params.get("half_life_last_access_days", 7.0))
+        half_life_created = float(params.get("half_life_created_days", 30.0))
 
         self.apply(days_since_access=f"max(0, ({now_ts} - @last_accessed)/86400.0)")
         self.apply(days_since_created=f"max(0, ({now_ts} - @created_at)/86400.0)")
-        self.apply(freshness=f"pow(2, -@days_since_access/{hl_la})")
-        self.apply(novelty=f"pow(2, -@days_since_created/{hl_cr})")
-        self.apply(recency=f"{wf}*@freshness+{wa}*@novelty")
+        self.apply(freshness=f"pow(2, -@days_since_access/{half_life_access})")
+        self.apply(novelty=f"pow(2, -@days_since_created/{half_life_created})")
+        self.apply(recency=f"{freshness_weight}*@freshness+{novelty_weight}*@novelty")
         self.apply(sim="1-(@__vector_score/2)")
-        self.apply(boosted_score=f"{w_sem}*@sim+{w_rec}*@recency")
+        self.apply(boosted_score=f"{semantic_weight}*@sim+{recency_weight}*@recency")
 
         return self
 

tests/test_forgetting.py

@@ -40,10 +40,10 @@ def make_result(
 
 def default_params():
     return {
-        "w_sem": 0.8,
-        "w_recency": 0.2,
-        "wf": 0.6,
-        "wa": 0.4,
+        "semantic_weight": 0.8,
+        "recency_weight": 0.2,
+        "freshness_weight": 0.6,
+        "novelty_weight": 0.4,
         "half_life_last_access_days": 7.0,
         "half_life_created_days": 30.0,
     }
@@ -87,8 +87,8 @@ def test_rerank_with_recency_prefers_recent_when_similarity_close():
 def test_rerank_with_recency_respects_semantic_weight_when_gap_large():
     # If semantic similarity difference is large, it should dominate
     params = default_params()
-    params["w_sem"] = 0.9
-    params["w_recency"] = 0.1
+    params["semantic_weight"] = 0.9
+    params["recency_weight"] = 0.1
     now = datetime.now(UTC)
 
     much_more_similar_old = make_result(

tests/test_recency_aggregation.py

@@ -21,10 +21,10 @@ async def test_recency_aggregation_query_builds_and_paginates():
         .apply_recency(
             now_ts=1_700_000_000,
             params={
-                "w_sem": 0.7,
-                "w_recency": 0.3,
-                "wf": 0.5,
-                "wa": 0.5,
+                "semantic_weight": 0.7,
+                "recency_weight": 0.3,
+                "freshness_weight": 0.5,
+                "novelty_weight": 0.5,
                 "half_life_last_access_days": 5.0,
                 "half_life_created_days": 20.0,
             },