refactor: resolve PR review comments on recency and MCP changes

- Move recency functions to utils.recency to eliminate circular imports
- Update MCP methods to return Pydantic objects instead of JSON strings
- Move imports to top of files now that circular dependencies are resolved

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

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

Author: abrookins

agent_memory_server/long_term_memory.py

@@ -1,11 +1,9 @@
-import hashlib
 import json
 import logging
 import numbers
 import time
 from collections.abc import Iterable
 from datetime import UTC, datetime, timedelta
-from math import exp, log
 from typing import Any
 
 from docket.dependencies import Perpetual
@@ -41,6 +39,11 @@
     MemoryTypeEnum,
 )
 from agent_memory_server.utils.keys import Keys
+from agent_memory_server.utils.recency import (
+    _days_between,
+    generate_memory_hash,
+    rerank_with_recency,
+)
 from agent_memory_server.utils.redis import (
     ensure_search_index_exists,
     get_redis_conn,
@@ -122,29 +125,6 @@ async def extract_memory_structure(memory: MemoryRecord):
     )  # type: ignore
 
 
-def generate_memory_hash(memory: MemoryRecord) -> str:
-    """
-    Generate a stable hash for a memory based on text, user_id, and session_id.
-
-    Args:
-        memory: MemoryRecord object containing memory data
-
-    Returns:
-        A stable hash string
-    """
-    # Create a deterministic string representation of the key content fields only
-    # This ensures merged memories with same content have the same hash
-    content_fields = {
-        "text": memory.text,
-        "user_id": memory.user_id,
-        "session_id": memory.session_id,
-        "namespace": memory.namespace,
-        "memory_type": memory.memory_type,
-    }
-    content_json = json.dumps(content_fields, sort_keys=True)
-    return hashlib.sha256(content_json.encode()).hexdigest()
-
-
 async def merge_memories_with_llm(
     memories: list[MemoryRecord], llm_client: Any = None
 ) -> MemoryRecord:
@@ -1363,74 +1343,6 @@ async def delete_long_term_memories(
     return await adapter.delete_memories(ids)
 
 
-# Seconds per day constant for time calculations
-SECONDS_PER_DAY = 86400.0
-
-
-def _days_between(now: datetime, then: datetime | None) -> float:
-    if then is None:
-        return float("inf")
-    delta = now - then
-    return max(delta.total_seconds() / SECONDS_PER_DAY, 0.0)
-
-
-def score_recency(
-    memory: MemoryRecordResult,
-    *,
-    now: datetime,
-    params: dict,
-) -> float:
-    """Compute a recency score in [0, 1] combining freshness and novelty.
-
-    - 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_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)
-
-    freshness_weight = float(params.get("freshness_weight", 0.6))
-    novelty_weight = float(params.get("novelty_weight", 0.4))
-
-    # Convert to decay rates
-    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)
-
-    freshness = exp(-access_decay_rate * days_since_access)
-    novelty = exp(-creation_decay_rate * days_since_created)
-
-    recency_score = freshness_weight * freshness + novelty_weight * novelty
-    # Clamp to [0, 1]
-    return max(0.0, min(1.0, recency_score))
-
-
-def rerank_with_recency(
-    results: list[MemoryRecordResult],
-    *,
-    now: datetime,
-    params: dict,
-) -> list[MemoryRecordResult]:
-    """Re-rank results using combined semantic similarity and recency.
-
-    score = semantic_weight * (1 - dist) + recency_weight * recency_score
-    """
-    semantic_weight = float(params.get("semantic_weight", 0.8))
-    recency_weight = float(params.get("recency_weight", 0.2))
-
-    def combined_score(mem: MemoryRecordResult) -> float:
-        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)
-
-
 def _is_numeric(value: Any) -> bool:
     """Check if a value is numeric (int, float, or other number type)."""
     return isinstance(value, numbers.Number)

agent_memory_server/mcp.py

@@ -3,7 +3,6 @@
 
 import ulid
 from mcp.server.fastmcp import FastMCP as _FastMCPBase
-from mcp.types import TextContent
 
 from agent_memory_server.api import (
     create_long_term_memory as core_create_long_term_memory,
@@ -451,28 +450,14 @@ async def search_long_term_memory(
             offset=offset,
         )
         results = await core_search_long_term_memory(payload)
-        import json as _json
-
-        return TextContent(
-            type="text",
-            text=_json.dumps(
-                MemoryRecordResults(
-                    total=results.total,
-                    memories=results.memories,
-                    next_offset=results.next_offset,
-                ).model_dump(mode="json")
-            ),
+        return MemoryRecordResults(
+            total=results.total,
+            memories=results.memories,
+            next_offset=results.next_offset,
         )
     except Exception as e:
         logger.error(f"Error in search_long_term_memory tool: {e}")
-        import json as _json
-
-        return TextContent(
-            type="text",
-            text=_json.dumps(
-                MemoryRecordResults(total=0, memories=[], next_offset=None).model_dump()
-            ),
-        )
+        return MemoryRecordResults(total=0, memories=[], next_offset=None)
 
 
 # Notes that exist outside of the docstring to avoid polluting the LLM prompt:
@@ -621,12 +606,7 @@ async def memory_prompt(
     if search_payload is not None:
         _params["long_term_search"] = search_payload
 
-    import json as _json
-
-    result = await core_memory_prompt(
-        params=MemoryPromptRequest(query=query, **_params)
-    )
-    return TextContent(type="text", text=_json.dumps(result.model_dump()))
+    return await core_memory_prompt(params=MemoryPromptRequest(query=query, **_params))
 
 
 @mcp_app.tool()

agent_memory_server/utils/recency.py

@@ -0,0 +1,98 @@
+"""Recency-related utilities for memory scoring and hashing."""
+
+import hashlib
+import json
+from datetime import datetime
+from math import exp, log
+
+from agent_memory_server.models import MemoryRecord, MemoryRecordResult
+
+
+# Seconds per day constant for time calculations
+SECONDS_PER_DAY = 86400.0
+
+
+def generate_memory_hash(memory: MemoryRecord) -> str:
+    """
+    Generate a stable hash for a memory based on text, user_id, and session_id.
+
+    Args:
+        memory: MemoryRecord object containing memory data
+
+    Returns:
+        A stable hash string
+    """
+    # Create a deterministic string representation of the key content fields only
+    # This ensures merged memories with same content have the same hash
+    content_fields = {
+        "text": memory.text,
+        "user_id": memory.user_id,
+        "session_id": memory.session_id,
+        "namespace": memory.namespace,
+        "memory_type": memory.memory_type,
+    }
+    content_json = json.dumps(content_fields, sort_keys=True)
+    return hashlib.sha256(content_json.encode()).hexdigest()
+
+
+def _days_between(now: datetime, then: datetime | None) -> float:
+    if then is None:
+        return float("inf")
+    delta = now - then
+    return max(delta.total_seconds() / SECONDS_PER_DAY, 0.0)
+
+
+def score_recency(
+    memory: MemoryRecordResult,
+    *,
+    now: datetime,
+    params: dict,
+) -> float:
+    """Compute a recency score in [0, 1] combining freshness and novelty.
+
+    - 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_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)
+
+    freshness_weight = float(params.get("freshness_weight", 0.6))
+    novelty_weight = float(params.get("novelty_weight", 0.4))
+
+    # Convert to decay rates
+    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)
+
+    freshness = exp(-access_decay_rate * days_since_access)
+    novelty = exp(-creation_decay_rate * days_since_created)
+
+    recency_score = freshness_weight * freshness + novelty_weight * novelty
+    return min(max(recency_score, 0.0), 1.0)
+
+
+def rerank_with_recency(
+    results: list[MemoryRecordResult],
+    *,
+    now: datetime,
+    params: dict,
+) -> list[MemoryRecordResult]:
+    """Re-rank results using combined semantic similarity and recency.
+
+    score = semantic_weight * (1 - dist) + recency_weight * recency_score
+    """
+    semantic_weight = float(params.get("semantic_weight", 0.8))
+    recency_weight = float(params.get("recency_weight", 0.2))
+
+    def combined_score(mem: MemoryRecordResult) -> float:
+        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)

agent_memory_server/utils/redis_query.py

@@ -4,8 +4,8 @@
 
 from redisvl.query import AggregationQuery, RangeQuery, VectorQuery
 
-# Import constants from long_term_memory module
-from agent_memory_server.long_term_memory import SECONDS_PER_DAY
+# Import constants from utils.recency module
+from agent_memory_server.utils.recency import SECONDS_PER_DAY
 
 
 class RecencyAggregationQuery(AggregationQuery):

agent_memory_server/vectorstore_adapter.py

@@ -35,6 +35,8 @@
     MemoryRecordResult,
     MemoryRecordResults,
 )
+from agent_memory_server.utils.recency import generate_memory_hash, rerank_with_recency
+from agent_memory_server.utils.redis_query import RecencyAggregationQuery
 
 
 logger = logging.getLogger(__name__)
@@ -417,9 +419,6 @@ def generate_memory_hash(self, memory: MemoryRecord) -> str:
             A stable hash string
         """
         # Use the same hash logic as long_term_memory.py for consistency
-        # Lazy import to avoid circular dependency
-        from agent_memory_server.long_term_memory import generate_memory_hash
-
         return generate_memory_hash(memory)
 
     def _apply_client_side_recency_reranking(
@@ -438,9 +437,6 @@ def _apply_client_side_recency_reranking(
             return memory_results
 
         try:
-            # Lazy import to avoid circular dependency
-            from agent_memory_server.long_term_memory import rerank_with_recency
-
             now = datetime.now(UTC)
             params = {
                 "semantic_weight": float(recency_params.get("semantic_weight", 0.8))
@@ -917,8 +913,6 @@ async def _search_with_redis_aggregation(
             )
 
         # Aggregate with APPLY/SORTBY boosted score via helper
-        # Lazy import to avoid circular dependency
-        from agent_memory_server.utils.redis_query import RecencyAggregationQuery
 
         now_ts = int(datetime.now(UTC).timestamp())
         agg = (