feat: complete client library parameter naming updates

Updates client library models and implementation with descriptive parameter names:
- Add new descriptive fields to RecencyConfig model alongside legacy ones
- Update client.py parameter mapping with precedence logic
- Add comprehensive test for parameter precedence validation
- Maintain full backward compatibility with legacy short names

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

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

Author: abrookins

agent-memory-client/agent_memory_client/client.py

@@ -675,14 +675,45 @@ async def search_long_term_memory(
         if recency is not None:
             if recency.recency_boost is not None:
                 payload["recency_boost"] = recency.recency_boost
-            if recency.w_sem is not None:
-                payload["recency_w_sem"] = recency.w_sem
-            if recency.w_recency is not None:
-                payload["recency_w_recency"] = recency.w_recency
-            if recency.wf is not None:
-                payload["recency_wf"] = recency.wf
-            if recency.wa is not None:
-                payload["recency_wa"] = recency.wa
+            # Handle both new descriptive names and legacy short names
+            # Prefer new descriptive names, fall back to old short names
+            semantic_weight = (
+                recency.semantic_weight
+                if recency.semantic_weight is not None
+                else recency.w_sem
+            )
+            if semantic_weight is not None:
+                payload["recency_semantic_weight"] = semantic_weight
+                payload["recency_w_sem"] = semantic_weight  # For backward compatibility
+
+            recency_weight = (
+                recency.recency_weight
+                if recency.recency_weight is not None
+                else recency.w_recency
+            )
+            if recency_weight is not None:
+                payload["recency_recency_weight"] = recency_weight
+                payload["recency_w_recency"] = (
+                    recency_weight  # For backward compatibility
+                )
+
+            freshness_weight = (
+                recency.freshness_weight
+                if recency.freshness_weight is not None
+                else recency.wf
+            )
+            if freshness_weight is not None:
+                payload["recency_freshness_weight"] = freshness_weight
+                payload["recency_wf"] = freshness_weight  # For backward compatibility
+
+            novelty_weight = (
+                recency.novelty_weight
+                if recency.novelty_weight is not None
+                else recency.wa
+            )
+            if novelty_weight is not None:
+                payload["recency_novelty_weight"] = novelty_weight
+                payload["recency_wa"] = novelty_weight  # For backward compatibility
             if recency.half_life_last_access_days is not None:
                 payload["recency_half_life_last_access_days"] = (
                     recency.half_life_last_access_days

agent-memory-client/agent_memory_client/models.py

@@ -250,12 +250,29 @@ class RecencyConfig(BaseModel):
     recency_boost: bool | None = Field(
         default=None, description="Enable recency-aware re-ranking"
     )
+    # Legacy short parameter names (deprecated)
     w_sem: float | None = Field(default=None, description="Weight for semantic score")
     w_recency: float | None = Field(
         default=None, description="Weight for recency composite"
     )
     wf: float | None = Field(default=None, description="Weight for freshness")
     wa: float | None = Field(default=None, description="Weight for age/novelty")
+
+    # New descriptive parameter names (preferred)
+    semantic_weight: float | None = Field(
+        default=None,
+        description="Weight for semantic similarity (preferred over w_sem)",
+    )
+    recency_weight: float | None = Field(
+        default=None, description="Weight for recency score (preferred over w_recency)"
+    )
+    freshness_weight: float | None = Field(
+        default=None, description="Weight for freshness component (preferred over wf)"
+    )
+    novelty_weight: float | None = Field(
+        default=None, description="Weight for novelty/age component (preferred over wa)"
+    )
+
     half_life_last_access_days: float | None = Field(
         default=None, description="Half-life (days) for last_accessed decay"
     )

agent-memory-client/tests/test_client.py

@@ -326,19 +326,63 @@ async def test_recency_config_payload(self, enhanced_test_client):
                 text="q", recency=rc, limit=5
             )
 
-            # Verify payload contained recency fields
+            # Verify payload contained recency fields (both old and new names for compatibility)
             args, kwargs = mock_post.call_args
             assert args[0] == "/v1/long-term-memory/search"
             body = kwargs["json"]
             assert body["recency_boost"] is True
+            # Old parameter names (for backward compatibility)
             assert body["recency_w_sem"] == 0.7
             assert body["recency_w_recency"] == 0.3
             assert body["recency_wf"] == 0.6
             assert body["recency_wa"] == 0.4
+            # New descriptive parameter names (preferred)
+            assert body["recency_semantic_weight"] == 0.7
+            assert body["recency_recency_weight"] == 0.3
+            assert body["recency_freshness_weight"] == 0.6
+            assert body["recency_novelty_weight"] == 0.4
             assert body["recency_half_life_last_access_days"] == 7
             assert body["recency_half_life_created_days"] == 30
             assert body["server_side_recency"] is True
 
+    async def test_recency_config_new_parameter_names(self, enhanced_test_client):
+        """Test that new descriptive parameter names work and take precedence."""
+        with patch.object(enhanced_test_client._client, "post") as mock_post:
+            mock_response = AsyncMock()
+            mock_response.raise_for_status.return_value = None
+            mock_response.json.return_value = MemoryRecordResults(
+                total=0, memories=[], next_offset=None
+            ).model_dump()
+            mock_post.return_value = mock_response
+
+            rc = RecencyConfig(
+                recency_boost=True,
+                semantic_weight=0.9,  # New parameter name should take precedence
+                w_sem=0.1,  # Old parameter name (should be ignored)
+                recency_weight=0.1,
+                freshness_weight=0.7,
+                novelty_weight=0.3,
+                half_life_last_access_days=5,
+                half_life_created_days=20,
+                server_side_recency=True,
+            )
+
+            await enhanced_test_client.search_long_term_memory(
+                text="test query", recency=rc, limit=10
+            )
+
+            # Verify new parameter names take precedence
+            args, kwargs = mock_post.call_args
+            body = kwargs["json"]
+            assert body["recency_boost"] is True
+            # Both old and new names should be present
+            assert body["recency_w_sem"] == 0.9  # Uses new value, not old
+            assert body["recency_semantic_weight"] == 0.9  # New parameter
+            assert body["recency_recency_weight"] == 0.1
+            assert body["recency_freshness_weight"] == 0.7
+            assert body["recency_novelty_weight"] == 0.3
+            assert body["server_side_recency"] is True
+
 
 class TestClientSideValidation:
     """Tests for client-side validation methods."""